Monitoraggio dei gadget

Questo documento descrive come utilizzare la nuova API per i gadget per il monitoraggio dei gadget di Analytics. Questa API offre un modello di dati migliorato e il monitoraggio del rendimento per raccogliere le statistiche dei report di Analytics per i tuoi gadget.

  1. Prima di iniziare
  2. Monitoraggio del gadget
  3. Metodi di monitoraggio
  4. Considerazioni sull'utilizzo
  5. Suggerimenti
 

Prima di iniziare

In Google Analytics, ogni dominio o sottodominio unico del sito web che aggiungi al tuo account viene monitorato in una vista (profilo) distinta e assegnato un ID dominio distinto. Poiché ogni gadget opera sul proprio sottodominio sul sito host di gmodules.com, è consigliabile monitorare ogni gadget che crei nella propria vista (profilo) e con un ID di dominio univoco.

Il modo più semplice per farlo è consentire a Google Analytics di generare un ID univoco per te.

  1. Per iniziare, accedi a Google Analytics o registrati per creare un account Google Analytics.
    • I nuovi utenti devono visualizzare una pagina di registrazione di nuovo account.
    • Gli utenti esistenti devono accedere alla pagina Impostazioni Analytics e fare clic su Aggiungi vista sito web (profilo). Assicurati di scegliere nuovo dominio.
  2. Inserisci un URL di sito web valido da una di queste pagine.
    3. Poiché l'URL del sito web è solo una stringa che il software Google Analytics accoppia al tuo ID dominio, questo URL può essere qualsiasi stringa di URL del sito web valida, prodotta o reale. Non installerai il codice di monitoraggio in nessuna pagina web e non avrai bisogno di accedere ad alcuna pagina del sito web.
  3. Fai clic sul pulsante per passare alla schermata successiva.
    4. Quando viene visualizzato lo snippet del codice di monitoraggio, copia l'ID dominio univoco in un blocco note. Lo snippet di codice generato automaticamente contiene questo ID dominio nel formato UA-123456-1.
  4. Fai clic sul pulsante Fine.
    5. Nell'elenco delle viste (profilo) dovresti vedere il nome dell'URL del tuo sito web. Puoi anche modificare il nome della vista (profilo) con un nome più significativo facendo clic sul link Modifica relativo alla vista (profilo) e poi nuovamente su Modifica.
  5. Utilizza l'ID dominio generato nel codice di monitoraggio del gadget.
    6. Gli ID dominio di Analytics assumono il formato:
    UA-123456-1
 

Monitoraggio del gadget

Il processo di monitoraggio del tuo gadget prevede tre aggiunte al codice del tuo gadget:

  1. È in corso l'attivazione della funzionalità.
  2. Creazione di un oggetto tracker in corso...
  3. Monitora il tuo gadget utilizzando uno dei due metodi seguenti.

Il seguente esempio di codice del gadget mostra ciascuna di queste aggiunte di codice, spiegate di seguito. Puoi utilizzare questo file di esempio per iniziare il tuo gadget.

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
  <ModulePrefs title="Analytics Test">
     <!-- Sets the feature -->
     <Require feature="com.google.gadgets.analytics" /> 
     <Require feature="setprefs" /> 
  </ModulePrefs>
  <UserPref 
      name="counter"
      datatype="hidden"
      default_value="0" />
  <Content type="html"> 
  <![CDATA[ 
      <script>
      // Track this gadget using Google Analytics.

      // Creates a tracking object and uses reportPageview method to call gadget view
      var ga = new _IG_GA("UA-00000-1");
      ga.reportPageview('/view/counterGadget');

      // Suppose, for example, you have a gadget with two counter buttons.
      // You can track interactions with those counters via Analytics.

      // Increment value of "counter" user preference
      function incrementCounter() {
         var count = prefs.getInt("counter");

         prefs.set("counter", count + 1);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Increment", "Button", 0);
      }

      // Reset value of "counter" userpref to 0
      function resetCounter(){
         prefs.set("counter", 0);

         // Tracks button click as an event
         ga.reportEvent("Counter Gadget", "Reset", "Button", 0);
      }
      </script>
      <form name="counter">
      <input type=button value="Reset" name="reset" onClick="resetCounter()">
      <input type=button value="Count" name="count" onClick="incrementCounter()">
      </form>
  ]]>
  </Content>
</Module>

1. Attivazione della funzionalità

Abilita innanzitutto la funzionalità importando la libreria di Analytics utilizzando lo spazio dei nomi delle caratteristiche:

 <Require feature="com.google.gadgets.analytics" />

2. Creazione di un oggetto tracker

L'API di monitoraggio di Analytics ottempera allo stesso modello orientato agli oggetti del codice di monitoraggio ga.js. Quindi, prima di monitorare il tuo gadget, crea l'istanza di un oggetto tracker:

var ga = new _IG_GA("UA-123456-1");

Qui inserirai l'ID dominio generato seguendo i passaggi precedenti.

Devi utilizzare l'ID dominio completo con il numero singolo finale, altrimenti la chiamata all'oggetto di monitoraggio non andrà a buon fine.

3. Monitoraggio del gadget

L'API dei gadget offre due metodi che puoi utilizzare per monitorare l'interazione con i tuoi gadget:

  • Il metodo dell'URL virtuale
    • ga.reportPageview(path);

    Questo metodo monitora le statistiche dei gadget come visualizzazioni di pagina speciali ed è lo stesso metodo utilizzato nella versione precedente dell'API per i gadget di Analytics. Con questo metodo, puoi aggiornare il codice di monitoraggio preesistente dei gadget senza influire sul layout dei rapporti Analytics esistenti. I dati dei report relativi ai gadget vengono visualizzati nello stesso modo in cui vengono visualizzati i dati dei report relativi alle pagine web.

    Quando utilizzi il metodo dell'URL virtuale per monitorare l'interazione con il gadget, ogni chiamata viene registrata come una richiesta di pagina per la stringa che fornisci come parametro per il metodo. Puoi sfruttare questo comportamento per trasmettere un percorso URL fabbricato in modo da poter visualizzare i report sui gadget nell'interfaccia di Google Analytics come faresti con i report sulle pagine del sito web. Ad esempio, puoi utilizzare percorsi separati per monitorare sia le visualizzazioni sia le interazioni con i gadget: 

    ga.reportPageview('/view/counterGadget');
ga.reportPageview('/click/increment');
ga.reportPageview('/click/reset');

  • Il metodo di monitoraggio degli eventi
    • ga.reportEvent(name, action, [[]label], [[]value]);

    Questo metodo è disponibile solo nella nuova API per i gadget di Analytics. Con questo metodo, puoi monitorare le visualizzazioni di pagina (ad es. il rendering dei gadget) separatamente dalle interazioni degli utenti sul tuo gadget.

    Nota: al momento, la funzionalità di monitoraggio eventi è in versione beta chiusa. Utilizza il metodo dell'URL virtuale se non disponi dell'accesso al monitoraggio eventi.

    Il metodo dell'evento ti offre un modello diverso da utilizzare con il monitoraggio dei gadget. Innanzitutto, le chiamate agli eventi vengono calcolate separatamente dalle chiamate per le visualizzazioni di pagina e i dati risultanti vengono mostrati in una parte distinta dei report sui contenuti di Google Analytics. Pertanto, potresti tenere traccia della visualizzazione di un gadget separatamente dalle interazioni dell'utente sul gadget, senza che l'interazione dell'utente aumenti il numero complessivo di visualizzazioni dei gadget. In secondo luogo, questo metodo utilizza il modello di monitoraggio degli eventi, la cui struttura è specificamente progettata per analizzare l'interazione dell'utente sui gadget. In questo modello, sia l'etichetta che il valore sono parametri facoltativi.

    Utilizzando l'esempio dei contatori, possiamo utilizzare il metodo evento per tenere traccia delle funzioni del gadget attivate e possiamo passare il tipo di controllo, che è un pulsante in entrambi i casi. 

    ga.reportEvent("Counter Gadget", "Increment", "Button");
ga.reportEvent("Counter Gadget", "Reset", "Button");

    Questo è un esempio molto semplice, ma il modello di monitoraggio eventi è una struttura altamente flessibile che puoi perfezionare per sfruttare i requisiti di monitoraggio specifici del tuo gadget. Per ulteriori informazioni, consulta la documentazione relativa agli eventi di monitoraggio.

 

Metodi di monitoraggio

Al momento, la funzionalità di Analytics offre i seguenti metodi. Il loro utilizzo è discusso sopra.

  • reportPageview()
    • Richiede una stringa per compilare correttamente i report sui contenuti. In genere questa stringa è sotto forma di percorso da te definito per i report. Il valore trasmesso a questo metodo viene inviato nella richiesta GIF tramite la variabile utmp. Utilizza questo metodo per monitorare i caricamenti e le interazioni con i gadget. 
    ga.reportPageview("/view/gadgetName");
    parametri
    String  path Percorso da fornire per l'URL virtuale di questo elemento.

  • reportEvent()
    • Richiede il nome del gadget e del parametro di azione per inserire correttamente i dati monitorati nei report sul monitoraggio eventi. Gli altri parametri sono facoltativi. I valori trasmessi tramite questo metodo vengono inviati nella visualizzazione di richiesta GIF per la variabile utmeU.

    parameters
    String  name  Obbligatorio.Una stringa utilizzata al livello superiore nei report Monitoraggio eventi. Ad esempio, se stai monitorando l'interazione su diversi elementi del gadget, probabilmente utilizzerai il nome del gadget stesso per questo parametro, in modo che il monitoraggio delle interazioni per il gadget venga aggregato nella stessa sezione dei report di Google Analytics.

    String  action  Obbligatorio. Stringa per segmentare ulteriormente l'interazione con il gadget nei report Monitoraggio eventi. Per ulteriori informazioni, consulta la documentazione relativa agli eventi di monitoraggio.

    String  label  Facoltativo. Stringa che puoi utilizzare come segmento secondario per il tuo gadget.

    Int  value  Facoltativo. Numero che puoi fornire come valore per l'interazione con il gadget. Questo numero viene aggregato per ogni volta che viene richiamato il metodo.

 

Considerazioni sull'utilizzo

L'API per i gadget di Google Analytics prevede una serie di considerazioni sull'utilizzo:

  • Contenitori supportati
    • L'API per il gadget di Google Analytics supporta molti tipi di contenitori, inclusi, a titolo esemplificativo:
    • iGoogle
    • Apri syndication
    • OpenSocial
    • Gadget
  • Tipi di gadget non supportati
    • L'API per i gadget di Google Analytics non supporta i seguenti tipi di gadget:
    • Gadget incorporati (type=html-inline)
    • Mapplet
    • Gadget del tipo di URL (type-url)
    • Gadget ad su Google AdSense
  • Considerazioni sul dominio
    • Quando richiedi la funzionalità Analytics per il tuo gadget, quest'ultimo reindirizzerà a <subdomain>.gmodules.com, dove <subdomain> è un sottodominio univoco e casuale. Quindi, tutti i contenuti del gadget vengono visualizzati sotto quel sottodominio. Esempio: 3nvma227-a.gmodules.com. Inoltre, tutti i cookie di monitoraggio di Google Analytics sono impostati su questo sottodominio univoco. Per questo motivo, le mapplet non sono supportate dalla funzione di monitoraggio di Analytics e devi concedere in modo specifico ai contenuti Flash un accesso speciale alla funzione di monitoraggio (vedi di seguito).
  • Gadget che utilizzano contenuti Flash
    • I gadget che utilizzano contenuti Flash devono abilitare specificatamente la comunicazione tra l'URL Flash e l'URL del gadget impostando il parametro allowScriptAccess su sempre. 
    _IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});
 

Suggerimenti

Come utilizzare al meglio il metodo dell'URL virtuale

Se non hai accesso al metodo di monitoraggio degli eventi per i tuoi gadget, segui questi consigli per monitorare i tuoi gadget con l'URL virtuale:

  • Segmenta il caricamento del gadget in modo distinto.
    • Puoi chiamare ga.reportPageview() al caricamento dei gadget fornendo un percorso che segmenti le statistiche di caricamento/visualizzazione dei gadget separatamente dalle metriche di interazione con i gadget. In questo modo i dati dei report sui contenuti per il gadget verranno conservati in una "directory" separata dalle interazioni sul gadget, in modo da poter vedere le visualizzazioni complessive separatamente dal numero di interazioni sul gadget stesso. Ad esempio, il seguente snippet di codice potrebbe essere utilizzato nel tuo gadget per visualizzare tutte le statistiche relative al caricamento del gadget: 
      ga.reportPageview('/view/gadgetName');
  • Segmentare i diversi tipi di interazione l'uno dall'altro.
    • Chiama ga.reportPageview() con un percorso che segmenta le diverse interazioni degli utenti. In questo modo, puoi ottenere report sui contenuti separati per i link dei gadget, i pulsanti dei gadget o altri widget che potresti voler monitorare per i dati sulle interazioni. Ecco alcuni esempi:
    • ga.reportPageview('/link/click');
    • ga.reportPageview('/link/submit');

Uso del metodo di monitoraggio eventi

Se hai accesso alla funzione Monitoraggio eventi nei rapporti di Google Analytics, puoi sfruttare il modello di dati altamente flessibile per ottenere il massimo dal monitoraggio dei tuoi oggetti. Ecco alcuni suggerimenti:

  • Monitora la visualizzazione o l'impressione del gadget utilizzando ga.reportPageview() e monitora l'interazione con il gadget utilizzando ga.reportEvent().
    • Le visualizzazioni dei gadget verranno visualizzate nella sezione Contenuti per i dati della pagina, mentre le interazioni con i gadget verranno visualizzate nella sezione Eventi dei report Contenuti.
  • Usa document.referrer come parametro per sapere dove è stato inserito il tuo gadget.
    • Nel gadget, document.referrer è di solito l'URL della pagina del contenitore, perciò puoi passarlo come parametro di etichetta nel metodo ga.reportEvent():
    var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

Risoluzione dei problemi

Puoi utilizzare strumenti di terze parti per analizzare la stringa di richiesta GIF per il tuo gadget al fine di verificare che i dati vengano inviati ai report di Google Analytics nel modo previsto. Quando il gadget è correttamente ospitato e funzionante nella pagina di test, analizza la stringa di richiesta GIF nel seguente modo:

  • Metodo di visualizzazione di pagina
    • Cerca la variabile utmp nei parametri della richiesta GIF. Le informazioni associate a tale variabile vengono inviate ai report di Google Analytics come "percorso" del gadget.
  • Metodo di monitoraggio eventi
    • Cerca la variabile utme nei parametri della richiesta GIF. Il formato delle informazioni deve essere 5(object*action*label)(value).

Per ulteriori informazioni sulla risoluzione dei problemi relativi al codice di monitoraggio, consulta la Guida alla risoluzione dei problemi di GATC.