Panoramica
Questo documento ti guiderà attraverso un esempio completo di come utilizzare l'API Embed. Al termine, visualizzerai un'applicazione simile a questa.
Creazione di una dashboard semplice
Per eseguire l'applicazione di esempio sul tuo server, segui questi due semplici passaggi:
- Crea un nuovo ID client
- Copia e incolla il codice.
Quando l'applicazione è in funzione, la sezione successiva spiegherà dettagliatamente come tutti i componenti si integrino.
Crea un nuovo ID client
L'API Embed gestisce quasi tutto il processo di autorizzazione al posto tuo, fornendo un componente di accesso con un solo clic che utilizza il familiare flusso OAuth 2.0. Per far funzionare questo pulsante sulla tua pagina, avrai bisogno di un ID client.
Se non hai mai creato un ID client, puoi farlo seguendo queste istruzioni.
Mentre segui le istruzioni, non dimenticare di non trascurare questi due passaggi fondamentali:
- Attivare l'API Analytics
- Imposta le origini corrette
Le origini controllano quali domini sono autorizzati a utilizzare questo codice per autorizzare gli utenti. In questo modo si impedisce ad altre persone di copiare il tuo codice e di eseguirlo sul proprio sito.
Ad esempio, se il tuo sito web è ospitato sul dominio example.com, assicurati di impostare la seguente origine per il tuo ID client http://example.com. Se vuoi testare il codice localmente, dovrai aggiungere anche l'origine per il server locale, ad esempio: http://localhost:8080.
Copia e incolla il codice
Una volta che hai impostato l'ID client con le origini corrette, puoi creare la demo. Copia e incolla il codice seguente in un file HTML sul plug-in del server nel tuo ID client dove è indicato: "Inserisci qui il tuo ID client".
<!DOCTYPE html>
<html>
<head>
<title>Embed API Demo</title>
</head>
<body>
<!-- Step 1: Create the containing elements. -->
<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>
<!-- Step 2: Load the library. -->
<script>
(function(w,d,s,g,js,fjs){
g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
js.src='https://apis.google.com/js/platform.js';
fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
<script>
gapi.analytics.ready(function() {
// Step 3: Authorize the user.
var CLIENT_ID = 'Insert your client ID here';
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
// Step 4: Create the view selector.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
// Step 5: Create the timeline chart.
var timeline = new gapi.analytics.googleCharts.DataChart({
reportType: 'ga',
query: {
'dimensions': 'ga:date',
'metrics': 'ga:sessions',
'start-date': '30daysAgo',
'end-date': 'yesterday',
},
chart: {
type: 'LINE',
container: 'timeline'
}
});
// Step 6: Hook up the components to work together.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
});
</script>
</body>
</html>
Procedura dettagliata per il codice
Questa sezione illustra dettagliatamente cosa succede nel codice fornito per l'applicazione di esempio. Una volta capito come funziona, dovresti essere in grado di crearne uno personalizzato.
Passaggio 1: crea i contenitori dei componenti
La maggior parte dei componenti dell'API Embed consente di visualizzare visivamente qualcosa sulla pagina. Per controllare la posizione di questi componenti, devi creare i container. Nell'applicazione di esempio sono presenti un pulsante di autenticazione, un selettore di viste e un grafico. Ognuno di questi componenti viene visualizzato all'interno dei seguenti elementi HTML:
<section id="auth-button"></section> <section id="view-selector"></section> <section id="timeline"></section>
Quando crei un componente, indichi quale container utilizzare in base al suo attributo ID, come vedrai negli esempi successivi.
Passaggio 2: carica la libreria
L'API Embed può essere caricata con il seguente snippet.
<script>
(function(w,d,s,g,js,fjs){
g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
js.src='https://apis.google.com/js/platform.js';
fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
Quando la libreria è stata completamente caricata, tutti i callback passati a gapi.analytics.ready verranno richiamati.
<script>
gapi.analytics.ready(function() {
// Put your application code here...
});
</script>
Passaggio 3: autorizza l'utente
L'API Embed gestisce quasi tutto il processo di autorizzazione al posto tuo, fornendo un componente di accesso con un solo clic che utilizza il familiare flusso OAuth 2.0. Per far funzionare questo pulsante sulla tua pagina, devi trasferire un riferimento contenitore e il tuo ID client.
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
Questo genererà un pulsante all'interno dell'elemento con l'ID "auth-button" che si occupa del flusso di autorizzazione per tuo conto.
Passaggio 4: crea il selettore della vista
Il componente selettore Vista può essere utilizzato per ottenere gli ID di una determinata vista, in modo da poter eseguire un report per la vista in questione.
Per creare un selettore vista, tutto ciò di cui hai bisogno è il riferimento al container che hai creato nel passaggio 1.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Viene creato il componente di selezione della vista, ma non viene ancora visualizzato nella pagina. Per farlo devi chiamare execute(), che viene gestito nel passaggio 6.
Passaggio 5: crea il grafico a cronologia
L'API Embed fornisce un componente grafico costituito da un grafico di Google e da un oggetto report in uno. Ciò semplifica notevolmente il processo di visualizzazione dei dati poiché l'oggetto del grafico esegue i report dietro le quinte e si aggiorna automaticamente con i risultati.
Per creare un componente grafico, devi specificare i parametri di query dell'API e le opzioni del grafico. All'interno delle opzioni del grafico è presente un riferimento all'ID del contenitore creato nel passaggio 1.
var timeline = new gapi.analytics.googleCharts.DataChart({
reportType: 'ga',
query: {
'dimensions': 'ga:date',
'metrics': 'ga:sessions',
'start-date': '30daysAgo',
'end-date': 'yesterday',
},
chart: {
type: 'LINE',
container: 'timeline'
}
});
Come per il selettore della vista, viene creato il componente del grafico, ma per visualizzarlo nella pagina devi chiamare execute(), come spiegato nel passaggio successivo.
Passaggio 6: collega i componenti in modo che interagiscano
I componenti API Embed emettono eventi quando si verificano varie cose, ad esempio un'autorizzazione riuscita, la selezione di una nuova vista o il rendering completo di un grafico.
L'applicazione di esempio in questa guida attende il rendering del selettore vista fino a quando è avvenuta l'autorizzazione e aggiorna il grafico a cronologia ogni volta che viene selezionata una nuova vista dal selettore.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
Per un elenco completo di tutti gli eventi emessi dai vari componenti, consulta il riferimento API.
Passaggi successivi
Questa guida ti ha spiegato come creare una visualizzazione di base con l'API Embed. Per saperne di più, consulta il riferimento API per comprendere appieno cosa è possibile.