Gadget-Tracking

In diesem Dokument wird die Verwendung der neuen API für das Analytics-Gadget-Tracking beschrieben. Dieses API bietet ein verbessertes Datenmodell und Leistungs-Tracking für die Erfassung von Analytics-Berichtstatistiken für Ihre Gadgets.

  1. Bevor Sie beginnen
  2. Tracking Ihres Gadgets
  3. Tracking-Methoden
  4. Verwendungshinweise
  5. Tipps
 

Vorbereitung

In Google Analytics wird jede Websitedomain oder Subdomain, die Sie Ihrem Konto hinzufügen, in einer separaten Datenansicht (Profil) erfasst und einer eigenen Domain-ID zugewiesen. Da jedes Gadgets auf der Host-Website von gmodules.com in einer eigenen Subdomain betrieben wird, möchten Sie jedes von Ihnen erstellte Gadgets in einer eigenen Ansicht (Profil) und mit einer eindeutigen Domain-ID verfolgen.

Am einfachsten ist es, wenn Google Analytics eine eindeutige ID für Sie erstellen lässt.

  1. Melden Sie sich zunächst in Google Analytics an oder erstellen Sie ein Google Analytics-Konto.
    • Neuen Nutzern wird die Seite Neues Konto registrieren angezeigt.
    • Bestehende Nutzer rufen die Seite Analytics-Einstellungen auf und klicken auf Website-Datenansicht (Profil) hinzufügen. Achten Sie darauf, dass Sie Neue Domain auswählen.
  2. Geben Sie auf einer dieser Seiten eine gültige Website-URL ein.
    3. Da die Website-URL nur ein String ist, der in der Google Analytics-Software mit Ihrer Domain-ID gekoppelt ist, kann diese URL ein beliebiger gültiger String einer Website-URL sein, unabhängig davon, ob sie gefälscht oder echt ist. Sie installieren den Tracking-Code auf keiner Website und benötigen auch keinen Zugriff auf die Seiten einer Website.
  3. Klicke auf die Schaltfläche, um zum nächsten Bildschirm zu gelangen.
    4. Wenn das Tracking-Code-Snippet angezeigt wird, kopieren Sie die eindeutige Domain-ID in ein Scratchpad. Das automatisch generierte Code-Snippet enthält diese Domain-ID im Format UA-123456-1.
  4. Klicken Sie auf die Schaltfläche Finish (Fertigstellen).
    5. Der Name Ihrer Website-URL sollte in der Liste der Datenansicht (Profil) zu sehen sein. Sie können den Namen der Datenansicht (des Profils) auch aussagekräftig ändern. Klicken Sie dazu für die entsprechende Datenansicht (Profil) auf den Link Bearbeiten und dann erneut auf Bearbeiten.
  5. Verwenden Sie die generierte Domain-ID im Tracking-Code Ihres Gadgets.
    6. Die Domain-IDs von Analytics haben das Format:
    UA-123456-1
 

Tracking Ihres Gadgets

Die Verfolgung Ihres Gadgets umfasst drei Zusätze:

  1. Die Funktion wird aktiviert.
  2. Erstellen eines Tracker-Objekts
  3. Verfolgen Ihres Gadgets mithilfe einer von zwei Methoden.

Das folgende Codebeispiel für Gadgets zeigt jede dieser Codeergänzungen, die nachfolgend erläutert werden. Sie können diese Beispieldatei verwenden, um Ihr eigenes Gadgets zu starten.

<?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. Funktion aktivieren

Aktivieren Sie zuerst die Funktion, indem Sie die Analytics-Bibliothek mithilfe des Funktions-Namespace importieren:

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

2. Tracker-Objekt erstellen

Die Analytics-Tracking-API richtet sich nach demselben objektorientierten Modell des ga.js-Tracking-Codes. Instanziieren Sie daher vor dem Tracking Ihres Gadgets ein Tracker-Objekt:

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

Hier fügen Sie die Domain-ID ein, die anhand der oben beschriebenen Schritte generiert wurde.

Sie müssen die vollständige Domain-ID mit der Endziffer verwenden. Andernfalls schlägt der Aufruf des Tracking-Objekts fehl.

3. Tracking Ihres Gadgets

Das Google Gadgets API bietet zwei Methoden, mit denen Sie Interaktionen mit Ihren Gadgets verfolgen können:

  • Methode „Virtuelle URL“
    • ga.reportPageview(path);

    Diese Methode verfolgt die Gadgets-Statistiken als spezielle Seitenaufrufe. Es handelt sich dabei um die gleiche Methode, die in der früheren Version des Analytics-Gadget-APIs verwendet wurde. Mit dieser Methode können Sie jeden bereits vorhandenen Gadgets-Tracking-Code aktualisieren, ohne das Layout Ihrer bestehenden Analytics-Berichte zu beeinträchtigen. Sie können Berichtsdaten für Ihre Gadgets genauso aufrufen wie die für Webseiten.

    Wenn Sie die virtuelle URL-Methode verwenden, um die Interaktionen eines Gadgets zu verfolgen, wird jeder Aufruf als Seitenanfrage für die Zeichenfolge erfasst, die Sie als Parameter für die Methode angeben. Sie können dieses Verhalten nutzen, um einen gefälschten URL-Pfad zu übergeben, sodass Sie Berichte für Gadgets in der Google Analytics-Benutzeroberfläche genau wie Berichte für Website-Seiten anzeigen können. So könnten Sie beispielsweise separate Pfade verwenden, um sowohl Gadgets-Ansichten als auch Gadgets-Interaktionen zu verfolgen: 

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

  • Ereignis-Tracking-Methode
    • ga.reportEvent(name, action, [[]label], [[]value]);

    Diese Methode ist nur in der neuen Analytics-Gadget-API verfügbar. Mit dieser Methode können Sie Seitenaufrufe (z.B. das Rendern eines Gadgets) getrennt von den Nutzerinteraktionen mit Ihrem Gerät erfassen.

    Hinweis: Das Ereignis-Tracking befindet sich derzeit in der geschlossenen Betaversion. Verwenden Sie die virtuelle URL-Methode, wenn Sie keinen Zugriff auf das Ereignis-Tracking haben.

    Die -Ereignismethode bietet ein anderes Modell für die Verwendung beim Tracking von Gadgets. Erstens werden Ereignisaufrufe getrennt von Seitenaufrufaufrufen berechnet. Die resultierenden Daten werden in einem separaten Teil der Google Analytics-Berichte zu Content angezeigt. Auf diese Weise können Sie die Ansicht eines Gadgets getrennt von den Nutzerinteraktionen verfolgen, ohne dass die Nutzerinteraktion die Gesamtzahl der Gadgets-Aufrufe in die Höhe treibt. Zweitens wird bei dieser Methode das Ereignis-Tracking-Modell verwendet, dessen Struktur speziell für die Analyse der Nutzerinteraktionen mit Gadgets entwickelt wurde. In diesem Modell sind sowohl das Label als auch der Wert optionale Parameter.

    Mithilfe des Zählerbeispiels können wir die -Ereignismethode verwenden, um zu verfolgen, welche Gadgets-Funktionen ausgelöst werden, und wir können den Steuerelementtyp übergeben, der in beiden Fällen eine Schaltfläche ist. 

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

    Dies ist ein sehr einfaches Beispiel, aber das Ereignisverfolgungsmodell ist eine äußerst flexible Struktur, die Sie optimieren können, um die einzigartigen Tracking-Anforderungen Ihres Gadgets zu nutzen. Weitere Informationen finden Sie in der Dokumentation zum Tracking von Ereignissen.

 

Tracking-Methoden

Derzeit stehen folgende Methoden für die Analytics-Funktion zur Verfügung: Ihre Verwendung wird oben erläutert.

  • reportPageview()
    • Erfordert einen String, damit die Contentberichte korrekt ausgefüllt werden. Normalerweise liegt dieser String in Form eines Pfades vor, den Sie für Ihre Berichterstellungszwecke definieren. Der an diese Methode übergebene Wert wird in der GIF-Anfrage über die Variable utmp gesendet. Verwenden Sie diese Methode, um das Laden und die Interaktionen von Gadgets nachzuverfolgen. 
    ga.reportPageview("/view/gadgetName");
    parameters
    String  path Pfad, der für die virtuelle URL dieses Elements angegeben werden soll.

  • reportEvent()
    • Damit die erfassten Daten richtig in Ereignis-Tracking-Berichte eingefügt werden können, sind der Name des Gadgets und der Aktionsparameter erforderlich. Die anderen Parameter sind optional. Die über diese Methode übergebenen Werte werden in der GIF-Anfrageansicht der utme-VariablenU gesendet.

    parameters
    String  name  Erforderlich.Ein String, der auf der obersten Ebene der Berichte zum Ereignis-Tracking verwendet wird. Wenn Sie beispielsweise Interaktionen für eine Reihe von Gadgets-Elementen nachverfolgen, würden Sie wahrscheinlich den Namen des Gadgets selbst für diesen Parameter verwenden, sodass sämtliches Interaktions-Tracking für das Gerät im selben Abschnitt der Google Analytics-Berichte zusammengefasst wird.

    String  action  Erforderlich. Zeichenfolge zur weiteren Segmentierung von Gadgets-Interaktionen in den Ereignis-Tracking-Berichten. Weitere Informationen finden Sie in der Dokumentation zum Tracking von Ereignissen.

    String  label  Optional. Zeichenfolge, die Sie als sekundäres Segment für Ihr Gerät verwenden können.

    Int  value  Optional. Zahl, die Sie als Wert für die Gadgets-Interaktion angeben können. Diese Zahl wird jedes Mal aggregiert, wenn die Methode aufgerufen wird.

 

Nutzungshinweise

Für die Verwendung der Google Analytics-Gadget-API ist Folgendes zu beachten:

  • Unterstützte Container
    • Viele Arten von Containern werden bei der Google Analytics Gadgets API unterstützt, unter anderem:
    • iGoogle
    • Offene Syndikation
    • OpenSocial
    • Gadgets
  • Nicht unterstützte Elementtypen
    • Folgende Gadgets werden von der Google Analytics Gadgets API nicht unterstützt:
    • Inline-Gadgets (type=html-inline)
    • Mapplets
    • URL-Typ-Gadgets (type-url)
    • Tablet-Anzeigen in Google AdSense
  • Überlegungen zu Domains
    • Wenn Sie die Analytics-Funktion für Ihr Gerät benötigen, werden Sie von Ihrem Gerät zu <subdomain>.gmodules.com weitergeleitet. Dabei ist <subdomain> eine eindeutige, zufällige Subdomain. Daher wird der gesamte Inhalt des Gadgets unter dieser Subdomain angezeigt. Beispiel: 3nvma227-a.gmodules.com. Außerdem werden alle Tracking-Cookies von Google Analytics auf diese eindeutige Subdomain gesetzt. Aus diesem Grund werden Mapplets von der Analytics-Tracking-Funktion nicht unterstützt und Sie müssen Flash-Inhalten speziellen Zugriff auf die Tracking-Funktion gewähren (siehe unten).
  • Gadgets, die Flash-Inhalte verwenden
    • Gadgets, die Flash-Inhalte verwenden, müssen ausdrücklich die Kommunikation zwischen der Flash-URL und der Gadgets-URL ermöglichen, indem der Parameter allowScriptAccess auf "immer" gesetzt wird. 
    _IG_EmbedFlash("example.swf", "wrapper", {allowScriptAccess: "always"});
 

Tipps

So verwenden Sie die virtuelle URL-Methode am besten

Wenn Sie keinen Zugriff auf die Ereignis-Tracking-Methode für Ihre Gadgets haben, befolgen Sie die folgenden Empfehlungen zum Tracking Ihrer Gadgets mit der virtuellen URL-Methode:

  • Das Laden Ihres Gadgets wird getrennt voneinander dargestellt.
    • Sie können das ga.reportPageview() beim Laden eines Gadgets aufrufen und einen Pfad angeben, in dem die Statistiken zum Laden/Aufrufen des Gadgets getrennt von den Interaktionsmesswerten des Gadgets segmentiert sind. Dadurch werden die Inhalts-Berichtsdaten für das Gadgets in einem anderen "Verzeichnis" von den Interaktionen mit dem Gerät gespeichert, sodass Sie Ihre Gesamtaufrufe getrennt von der Anzahl der Interaktionen mit dem Gadgets selbst sehen können. Beispielsweise könnte das folgende Code-Snippet in Ihrem Gadgets verwendet werden, um alle Statistiken für die Ladezeit Ihres Gadgets anzuzeigen: 
      ga.reportPageview('/view/gadgetName');
  • Verschiedene Interaktionstypen voneinander segmentieren
    • Rufen Sie die ga.reportPageview() über einen Pfad auf, der verschiedene Nutzerinteraktionen segmentiert. So erhalten Sie separate Content-Berichte für Gadgets-Links, -Schaltflächen und andere Widgets, die Sie für Interaktionsdaten erfassen möchten. Beispiele:
    • ga.reportPageview('/link/click');
    • ga.reportPageview('/link/submit');

Ereignis-Tracking-Methode verwenden

Wenn Sie Zugriff auf die Ereignis-Tracking-Funktion in den Google Analytics-Berichten haben, können Sie das äußerst flexible Datenmodell nutzen, um das Tracking Ihrer Objekte optimal zu nutzen. Hier einige Tipps:

  • Verfolgen Sie den Aufruf oder die Impression des Gadgets mit ga.reportPageview(), und erfassen Sie die Gadgets-Interaktionen mit ga.reportEvent().
    • Gadget-Ansichten werden im Bereich „Content“ für Seitendaten angezeigt und Interaktionen zwischen Gadgets werden im Abschnitt „Ereignisse“ unter „Content-Berichte“ aufgeführt.
  • Verwenden Sie document.referrer als Parameter, um herauszufinden, wo Ihr Gerät platziert wurde.
    • Im Gadgets ist document.referrer normalerweise die Seiten-URL des Containers, sodass Sie sie als Label-Parameter in der ga.reportEvent()-Methode übergeben können:
    var containerPage = document.referrer;
ga.reportEvent("Counter Gadget", "Increment", containerPage, 0);

Fehlerbehebung

Sie können Tools von Drittanbietern verwenden, um den GIF-Anforderungs-String für Ihr Gadgets zu analysieren, um zu überprüfen, ob die Daten wie erwartet an die Google Analytics-Berichte gesendet werden. Sobald das Gadgets ordnungsgemäß auf Ihrer Testseite gehostet wird und funktioniert, analysieren Sie die GIF-Anforderungszeichenfolge wie folgt:

  • Seitenaufrufmethode
    • Suchen Sie die Variable utmp in den GIF-Anfrageparametern. Die mit dieser Variablen verknüpften Informationen werden an die Google Analytics-Berichte als "Pfad" für das Gadgets gesendet.
  • Ereignis-Tracking-Methode
    • Suchen Sie die Variable „utme“ in den GIF-Anfrageparametern. Diese Informationen müssen das Format 5(object*action*label)(value) haben.

Weitere Informationen zur Fehlerbehebung beim Tracking-Code finden Sie in der GATC-Anleitung zur Fehlerbehebung.