Einführung in ga.js (alt)

ga.js ist eine JavaScript-Bibliothek, mit der Sie messen können, wie Nutzer mit Ihrer Website interagieren. Dies ist eine Legacy-Bibliothek. Wenn Sie Google Analytics erst seit Kurzem nutzen, sollten Sie die neueste Tracking-Bibliothek, analytics.js, verwenden.

Kurzanleitung zum Tracking-Code

Das Analytics-Snippet ist ein kleines JavaScript-Code-Snippet, das Sie in Ihre Seiten einfügen. Es aktiviert das Google Analytics-Tracking durch Einfügen von ga.js in die Seite. Wenn du es auf deinen Seiten verwenden möchtest, kopiere das folgende Code-Snippet und ersetze UA-XXXXX-X durch deine Web-Property-ID. Fügen Sie dieses Snippet in Ihre Websitevorlagenseite vor dem schließenden </head>-Tag ein.

Wenn Sie mehr als das grundlegende Seiten-Tracking ausführen müssen, finden Sie in der Tracking-Referenz eine Liste der in der API verfügbaren Methoden. Informationen zur Verwendung der asynchronen Syntax finden Sie im Nutzungsleitfaden. Eine detaillierte Anleitung zum Einrichten des Trackings finden Sie im Hilfeartikel Tracking einrichten.

<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

Das obige Snippet stellt die Mindestkonfiguration dar, die für das asynchrone Tracking einer Seite erforderlich ist. Dabei wird _setAccount verwendet, um die Web-Property-ID der Seite festzulegen, und dann _trackPageview aufgerufen, um die Tracking-Daten zurück an die Google Analytics-Server zu senden.

Wichtig:Wenn Sie Ihre Seiten vom herkömmlichen Snippet auf die neueste, asynchrone Version aktualisieren, sollten Sie zuerst das vorhandene Tracking-Snippet entfernen. Wir raten davon ab, beide Snippets auf derselben Seite zu verwenden. Eine Migrationsanleitung finden Sie unter Zu Async migrieren.

Funktionsweise der asynchronen Syntax

Das _gaq-Objekt macht die asynchrone Syntax möglich. Sie fungiert als eine Warteschlange. Dabei handelt es sich um eine First-In-First-Out-Datenstruktur, die API-Aufrufe sammelt,bis ga.js zur Ausführung bereit ist. Verwenden Sie die Methode _gaq.push, um der Warteschlange etwas hinzuzufügen.

Um einen API-Aufruf in die Warteschlange zu verschieben, müssen Sie ihn von der herkömmlichen JavaScript-Syntax in ein Befehlsarray konvertieren. Befehlsarrays sind einfache JavaScript-Arrays, die einem bestimmten Format entsprechen. Das erste Element in einem Befehlsarray ist der Name der Tracker-Objektmethode, die Sie aufrufen möchten. Er muss ein String sein. Die restlichen Elemente sind die Argumente, die Sie an die Tracker-Objektmethode übergeben möchten. Dabei kann es sich um beliebige JavaScript-Werte handeln.

Mit dem folgenden Code wird _trackPageview() unter Verwendung der herkömmlichen Syntax aufgerufen:

var pageTracker = _gat._getTracker('UA-XXXXX-X');
pageTracker._trackPageview();

Der entsprechende Code in der asynchronen Syntax erfordert zwei Aufrufe von _gaq.push.

_gaq.push(['_setAccount', 'UA-XXXXX-X']);
_gaq.push(['_trackPageview']);

In der asynchronen Syntax ist die Erstellung des Tracker-Objekts impliziert, es muss jedoch immer noch eine Möglichkeit bestehen, die Web-Property-ID für den Tracker festzulegen. Dafür wurde die Methode _setAccount hinzugefügt. Alle anderen Tracker-Objektmethoden sind sowohl beim asynchronen als auch beim herkömmlichen Tracking identisch. Nur die Syntax ist anders.

Weitere Informationen zur asynchronen Syntax finden Sie in der Tracking-Referenz für die Methode _gaq.push.

Zurück nach oben

Tracking mit HTML-Event-Handlern

Die asynchrone Tracking-Syntax sollte auch in DOM-Ereignis-Handlern verwendet werden. Über die folgende Schaltfläche wird beispielsweise ein Ereignis generiert, wenn darauf geklickt wird.

<button onclick="_gaq.push(['_trackEvent', 'button3', 'clicked'])"></button>

Auch wenn auf diese Schaltfläche geklickt wird, bevor der Browser ga.js vollständig geladen hat, wird das Ereignis erfasst und schließlich ausgeführt. Bei Verwendung des herkömmlichen Trackings kann der Browser in diesem Fall eine Ausnahme ausgeben.

Zurück nach oben

Funktionen in die Warteschlange verschieben

Zusätzlich zu Befehlsarrays können Sie auch Funktionsobjekte in die _gaq-Warteschlange verschieben. Die Funktionen können beliebiges JavaScript enthalten. Genau wie Befehlsarrays werden sie in der Reihenfolge ausgeführt, in der sie auf _gaq übertragen werden. Diese Technik ist nützlich, um die Tracking-APIs aufzurufen, die Werte zurückgeben. Mit dem folgenden Code wird beispielsweise eine Verknüpfungs-URL erstellt und die Eigenschaft href für einen Link mit dem Ergebnis festgelegt.

_gaq.push(function() {
  var pageTracker = _gat._getTracker('UA-XXXXX-X');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

Im obigen Beispiel wird _gat verwendet, um ein Tracker-Objekt zu erstellen. Da es jedoch einer lokalen Variablen zugewiesen ist, kann es von einem Code außerhalb der Funktion nicht verwendet werden. Dies ist zwar akzeptabel, aber Sie können mit der Methode _gat._createTracker ein dauerhaftes, global zugängliches Objekt erstellen. Der folgende Code zeigt, wie dies funktionieren würde.

_gaq.push(function() {
  var pageTracker = _gat._createTracker('UA-XXXXX-X', 'myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

_gaq.push(['myTracker._trackPageview']);

Im obigen Beispiel wird ein asynchroner Tracker innerhalb der Funktion erstellt und später mit dem Namen im Befehlsarray darauf verwiesen.

Umgekehrter Anwendungsfall ist ebenfalls möglich. Wenn Sie beispielsweise ein asynchrones Tracker-Objekt verwenden müssen, das über ein zuvor übertragenes Befehlsarray erstellt wurde, nutzen Sie die Methode _gat._getTrackerByName. Der folgende Code veranschaulicht die Funktionsweise.

_gaq.push(['myTracker._setAccount', 'UA-XXXXX-X']);

_gaq.push(function() {
  var pageTracker = _gat._getTrackerByName('myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

Zurück nach oben

One Push, mehrere Befehle

Anstatt _gaq.push(...) für jeden Aufruf einzugeben, können Sie alle Befehle auf einmal übertragen. Der folgende Code veranschaulicht diese Technik.

_gaq.push(
  ['_setAccount', 'UA-XXXXX-X'],
  ['_setDomainName', 'example.com'],
  ['_setCustomVar', 1, 'Section', 'Life & Style', 3],
  ['_trackPageview']
);

Dies funktioniert, weil die Methode _gaq.push die Methode Array.push imitiert, mit der mehrere Elemente mit einem einzigen Aufruf übertragen werden können.

Zurück nach oben

Snippet aufteilen

Wenn Sie das Analytics-Snippet lieber unten auf der Seite platzieren möchten, müssen Sie nicht das gesamte Snippet unten auf der Seite platzieren. Sie können dennoch die meisten Vorteile des asynchronen Ladens nutzen, indem Sie das Snippet in zwei Hälften aufteilen. Die erste Hälfte sollte oben auf der Seite angezeigt werden und der Rest nach unten. Da der erste Teil des Tracking-Snippets wenig oder gar keine Auswirkungen auf das Seiten-Rendering hat, können Sie diesen Teil oben belassen und den Teil des Snippets, über den ga.js eingefügt wird, ganz unten platzieren.

Eine Seite, auf der das asynchrone Snippet in zwei Hälften aufgeteilt ist, könnte so aussehen:

<html>

<head>
  <script type="text/javascript">
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-XXXXX-X']);
    _gaq.push(['_trackPageview']);
  </script>
</head>

<body>
  <p>Page Content</p>

  <script src="some_random_script.js"></script>

  <p>Page Content</p>

  <script type="text/javascript">  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script> </body> </html>

Beide Codeteile müssen in eigene Skript-Tags umschlossen werden, aber nur die letzten sechs Zeilen des ursprünglichen asynchronen Snippets müssen nach unten verschoben werden. Alle Zeilen, die Methoden an _gaq senden, können oben bleiben.

Zurück nach oben

Häufige Fallstricke vermeiden

Beachten Sie bei Verwendung der asynchronen oder traditionellen Syntax Folgendes:

  • Bei Methodennamen wird zwischen Groß- und Kleinschreibung unterschieden.
    Wenn Sie einen Methodennamen ohne korrekte Groß- und Kleinschreibung verwenden, funktionieren die Methodenaufrufe nicht. Beispiele:
    _gaq.push(['_trackpageview']);   // bad
    _gaq.push(['_trackPageview']);   // good
  • Verwenden Sie die richtigen Methodennamen.
    Wenn das Tracking nicht richtig funktioniert, prüfen Sie, ob Sie den richtigen Namen für die Methode verwenden. Beispiele:
    _gaq.push(['_setDomain', 'example.com']);       // bad
    _gaq.push(['_setDomainName', 'example.com']);   // good
    
  • Nur Strings dürfen in Anführungszeichen übergeben werden. Für alle anderen Typen darf keine Anführungszeichen verwendet werden.
    Jeder Wert, der kein String ist, z. B. boolesche Werte, Objektliterale, Funktionen oder Arrays, sollte ohne Anführungszeichen übergeben werden. Verwenden Sie nur Anführungszeichen, wenn Sie etwas übergeben, das als String interpretiert werden soll. Wenn Sie von der herkömmlichen Syntax migrieren, sollten alle Funktionsparameter, die ohne Anführungszeichen übergeben wurden, in der asynchronen Syntax ohne Anführungszeichen bleiben. Beispiele:
    _gaq.push(['_setAllowLinker', 'false']);    // bad
    _gaq.push(['_setAllowLinker', false]);      // good
    
  • Strings dürfen keine Leerzeichen am Anfang oder Ende enthalten.
    Beispiele:
    _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
    _gaq.push(['_setAccount', 'UA-65432-1']);     // good
    

Zurück nach oben

Tracking deaktivieren

In einigen Fällen kann es erforderlich sein, den Google Analytics-Tracking-Code auf einer Seite zu deaktivieren, ohne das Code-Snippet entfernen zu müssen. Dies ist beispielsweise der Fall, wenn die Datenschutzerklärung Ihrer Website die Möglichkeit einschließt, dass Besucher Google Analytics-Tracking deaktivieren können.

Das Tracking-Snippet ga.js enthält jetzt eine Window-Property. Wenn sie auf true gesetzt ist, werden über das Tracking-Snippet keine Daten an Google Analytics gesendet. Wenn Google Analytics versucht, ein Cookie zu setzen oder Daten an die Google Analytics-Server zurückzusenden, wird überprüft, ob diese Property auf true gesetzt ist. Ist dies der Fall, hat sie denselben Effekt, als ob auf dem Besucher das Browser-Plug-in zur Deaktivierung von Google Analytics installiert wäre.

Um das Tracking zu deaktivieren, setzen Sie die folgende window -Eigenschaft auf "true":

window['ga-disable-UA-XXXXXX-Y'] = true;

Der Wert UA-XXXXXX-Y entspricht dabei der ID der Web-Property, für die Sie das Tracking deaktivieren möchten.

Diese Fenstereigenschaft muss festgelegt werden, bevor der Tracking-Code aufgerufen wird. Diese Property muss auf jeder Seite festgelegt werden, für die Sie Google Analytics-Tracking deaktivieren möchten. Wenn die Property nicht festgelegt oder auf „false“ gesetzt ist, funktioniert das Tracking wie gewohnt.

Wenn Ihr Google Analytics-Tracking-Code auf einer Seite beispielsweise Folgendes enthält:

_gaq.push['_setAccount', 'UA-123456-1']

Sie möchten verhindern, dass der Tracking-Code Cookies setzt oder Daten an Google Analytics zurücksendet. In diesem Fall verwenden Sie den folgenden Code, bevor der Tracking-Code aufgerufen wird:

window['ga-disable-UA-123456-1'] = true;

Wenn Sie auf einer Seite mehrere Tracker mit mehreren Web-Property-IDs verwenden, müssen Sie die entsprechende window['ga-disable-UA-XXXXXX-Y']-Variable für jede Web-Property auf true setzen, um das Google Analytics-Tracking auf dieser Seite vollständig zu deaktivieren.

Beispiel

Hier ist ein einfaches Beispiel für Code, mit dem du deinen Nutzern eine Deaktivierungsfunktion zur Verfügung stellen kannst.

Fügen Sie Ihrer Website zunächst einen neuen HTML-Link hinzu, um die Deaktivierungslogik auszuführen:

<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>

Fügen Sie dann das folgende Code-Snippet vor dem Code-Snippet "ga.js" ein. Achte darauf, den Wert von gaProperty aus UA-XXXX-Y durch die auf deiner Website verwendete Property zu ersetzen. Dies ist der gleiche Wert, den Sie an den Befehl _setAccount übergeben.

<script>
// Set to the same value as the web property used on the site
var gaProperty = 'UA-XXXX-Y';

// Disable tracking if the opt-out cookie exists.
var disableStr = 'ga-disable-' + gaProperty;
if (document.cookie.indexOf(disableStr + '=true') > -1) {
  window[disableStr] = true;
}

// Opt-out function
function gaOptout() {
  document.cookie = disableStr + '=true; expires=Thu, 31 Dec 2099 23:59:59 UTC; path=/';
  window[disableStr] = true;
}
</script>

Wenn ein Nutzer auf den HTML-Link zum Deaktivieren klickt, wird die benutzerdefinierte Funktion gaOptout ausgeführt. Es wird über einen längeren Zeitraum ein Cookie gesetzt und die Erfassung von analytics.js-Daten deaktiviert. Kehrt ein Nutzer zu dieser Website zurück, überprüft das obige Skript, ob das Deaktivierungs-Cookie gesetzt wurde. Ist dies der Fall, wird auch die Datenerfassung in analytics.js deaktiviert.

SSL erzwingen (HTTPS)

Damit Google Analytics Daten immer über SSL sendet, auch von unsicheren Seiten (HTTP), verwenden Sie die Methode _gat._forceSSL wie in diesem Beispiel:

_gaq.push(['_setAccount', 'UA-12345-1']);
_gaq.push(['_gat._forceSSL']);       // Send all hits using SSL, even from insecure (HTTP) pages.
_gaq.push(['_trackPageview']);

Zurück nach oben