Per iniziare

Panoramica

Questo documento ti guiderà in un esempio completo di come utilizzare l'API Embed. Dopo aver completato l'operazione, avrai un'applicazione simile alla seguente.

Uno screenshot dell'esempio trattato in questa guida
Uno screenshot dell'esempio trattato in questa guida.

Creare una dashboard semplice

Puoi avviare l'applicazione di esempio sul tuo server seguendo questi due semplici passaggi:

  1. Crea un nuovo ID client
  2. Copia e incolla il codice

Dopo aver installato questa applicazione, nella sezione successiva viene spiegato dettagliatamente come si combinano tutti i componenti.

Crea un nuovo ID client

L'API Embed gestisce quasi tutta la procedura di autorizzazione per te fornendo un componente di accesso con un clic che utilizza il flusso OAuth 2.0 familiare. Affinché questo pulsante funzioni sulla tua pagina, devi avere un ID client.

Se non hai mai creato un ID client, puoi farlo seguendo queste istruzioni.

Mentre osservi le istruzioni, è importante non trascurare questi due passaggi fondamentali:

  • Attivare l'API Analytics
  • Imposta le origini corrette

Le origini controllano i domini autorizzati a utilizzare questo codice per autorizzare gli utenti. Questo impedisce ad altre persone di copiare il tuo codice ed 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 verificare il tuo codice in locale, devi aggiungere l'origine anche per il tuo server locale, ad esempio: http://localhost:8080.

Copia e incolla il codice

Dopo aver 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 nell'ID client in cui è riportato: "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 di programmazione del codice

Questa sezione ti guiderà passo passo nell'esatto contenuto del codice fornito per l'applicazione di esempio. Una volta compreso come funziona, dovresti essere in grado di crearne di nuovi.

Passaggio 1: crea i container dei componenti

La maggior parte dei componenti dell'API Embed esegue il rendering visivo della pagina nella pagina. Puoi controllare dove posizionare questi componenti creando container per loro. Nell'applicazione di esempio sono disponibili un pulsante di autenticazione, un selettore vista 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, gli comunichi quale container utilizzare con il 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>

Al termine del caricamento della libreria, verranno richiamati tutti i callback trasmessi a gapi.analytics.ready.

<script>
gapi.analytics.ready(function() {
  // Put your application code here...
});
</script>

Passaggio 3: autorizza l'utente

L'API Embed gestisce quasi tutta la procedura di autorizzazione per te fornendo un componente di accesso con un solo clic che utilizza il flusso OAuth 2.0 familiare. Affinché questo pulsante funzioni sulla tua pagina, devi trasmettere un riferimento contenitore e il tuo ID client.

gapi.analytics.auth.authorize({
  container: 'auth-button',
  clientid: CLIENT_ID,
});

In questo modo verrà generato un pulsante all'interno dell'elemento con il pulsante 'auth-button' ID che si occupa del flusso di autorizzazione per te.

Passaggio 4: crea il selettore vista

Il componente Selettore vista può essere utilizzato per ottenere gli ID di una determinata vista, in modo da poter eseguire un report.

Per creare un selettore vista, ti serve soltanto il riferimento al container che hai creato nel passaggio 1.

var viewSelector = new gapi.analytics.ViewSelector({
  container: 'view-selector'
});

In questo modo, il componente del selettore vista non viene ancora visualizzato nella pagina. Per farlo, devi chiamare execute(), che viene gestito nel passaggio 6.

Passaggio 5: crea il grafico della sequenza temporale

L'API Embed fornisce un componente grafico che è insieme un grafico di Google e un oggetto report in uno. Questo semplifica notevolmente il processo di visualizzazione dei dati, poiché l'oggetto del grafico eseguirà i report dietro le quinte e si aggiornerà automaticamente con i risultati.

Per creare un componente del grafico, devi specificare i parametri di ricerca 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 con il selettore vista, viene creato il componente del grafico, ma per essere visualizzato nella pagina devi chiamare execute(), come illustrato nel passaggio successivo.

Passaggio 6: collega i componenti per lavorare insieme

I componenti API incorporati emettono eventi quando si verificano varie operazioni, ad esempio l'autorizzazione, la selezione di una nuova visualizzazione o la visualizzazione completa di un grafico.

L'applicazione di esempio in questa guida attende il rendering del selettore di vista fino a quando non viene concessa l'autorizzazione e aggiorna il grafico della sequenza temporale ogni volta che viene selezionata una nuova vista dal selettore di vista.

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 capire appieno cosa è possibile fare.