Google Tag API-Referenz

Das Google-Tag (gtag.js) API besteht aus einer einzelnen Funktion (gtag()) mit der folgenden Syntax:

gtag(<command>, <command parameters>);
  • <command> ist einer der folgenden Befehle:
  • <command parameters> sind die Parameter, die Sie an gtag() übergeben können. Befehlsparameter variieren je nach Befehl. Weitere Informationen finden Sie in der Befehlsreferenz unten.

Sie können gtag()-Befehle an einer beliebigen Stelle auf Ihrer Seite aufrufen, solange sie unter dem Google-Tag-Snippet angezeigt werden. Informationen dazu, wie Sie das Snippet einer Seite hinzufügen, finden Sie in der Installationsanleitung.

config

Hierüber können Sie zusätzliche Konfigurationsinformationen zu Zielen hinzufügen. In der Regel ist dies eine produktspezifische Konfiguration für ein Produkt. Sie müssen diese Konfiguration jedoch nur einmal konfigurieren, wenn Sie sowohl Google Ads als auch Google Analytics verwenden.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID> ist eine Kennung, mit der das Ziel für Treffer eindeutig identifiziert wird, z. B. eine Google Analytics-Property oder ein Google Ads-Konto. <additional_config_info> ist ein oder mehrere Parameter/Wert-Paare.

In diesem Beispiel wird ein Tag konfiguriert, das Daten an ein Google Ads-Konto sendet:

gtag('config', 'TAG_ID');

Dabei ist „TAG_ID“ die Tag-ID für das Google-Tag.

Im folgenden Beispiel wird gezeigt, wie Sie zusätzliche Konfigurationsinformationen senden. Dazu wird ein Tag konfiguriert, das Daten mit einem send_page_view-Parameter, der einen Wert von false übergibt, und einem groups-Parameter, der einen 'agency'-Wert an ein Analytics-Konto sendet.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

get

Hiermit können Sie verschiedene Werte aus gtag.js abrufen, einschließlich der Werte, die mit dem Befehl set festgelegt wurden.

gtag('get', '<target>', '<field_name>', callback)
Argument Typ Beispiel Beschreibung
<Ziel> string G-XXXXXXXXXX

Das Ziel, aus dem Werte abgerufen werden sollen.
<Feldname> Feldname client_id Der Name des abzurufenden Feldes.
callback Function (field) => console.log(field)

Eine Funktion, die mit dem angeforderten Feld aufgerufen wird, oder undefined, wenn es nicht festgelegt ist.

Feldname

Der Feldname kann der Name eines benutzerdefinierten Feldes, das Sie mit dem Befehl gtag('set') festgelegt haben, oder einer der folgenden Werte sein:

Feldname Unterstützte Ziele
client_id
  • Google Analytics 4
  • Universal Analytics
session_id
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Beispiele

Zusatzversprechen 

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Ereignis an das Measurement Protocol senden 

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Von Ihnen festgelegten Wert abrufen 

gtag('set', {currency: 'USD'});

gtag('get', 'G-XXXXXXXXXX', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

set

Ermöglicht das Festlegen von Werten, die für alle nachfolgenden gtag()-Aufrufe auf der Seite beibehalten werden.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

<parameter-value-pair> ist ein Schlüsselname und der Wert, der für gtag()-Aufrufe beibehalten werden soll. Mit dem folgenden Code werden beispielsweise der Wert von country auf 'US' und der Wert von currency auf 'USD' für alle nachfolgenden Ereignisse auf der Seite festgelegt:

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

Der Befehl set unterscheidet sich von der direkten Übergabe von Werten an den Befehl event. Wenn Sie Werte direkt an einen event-Befehl übergeben, gelten sie nur für das ausgelöste Ereignis. Mit set bleiben die Werte jedoch auf der aktuellen Seite erhalten und werden mit allen nachfolgenden Ereignissen übergeben. Veranschaulichen Sie die folgenden beiden Beispiele:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

und

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

Im ersten Beispiel wird das Ereignis login mit dem Wert method von 'Google' und das Ereignis share ohne Parameter übergeben. Im zweiten Beispiel werden sowohl login als auch share mit dem method-Wert 'Google' übergeben.

event

Verwenden Sie den Befehl event, um Ereignisdaten zu senden.

gtag('event', '<event_name>', {<event_params>});

<event_name> ist entweder:

<event_params> ist ein oder mehrere Parameter/Wert-Paare. Jedes Paar ist durch ein Komma getrennt.

Mit dem folgenden event-Befehl wird das empfohlene Ereignis screen_view mit zwei Parametern ausgelöst: app_name und screen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

Mit dem Befehl consent können Sie die Einwilligung konfigurieren.

gtag('consent', {<consent_arg>}, {<consent_params>});

Weitere Informationen zum Verhalten dieser Parameter finden Sie in der Google Analytics-Hilfe.

<consent_arg> ist entweder 'default' oder 'update'. Mit 'default' werden die standardmäßigen Einwilligungsparameter festgelegt, die verwendet werden sollen. Mit 'update' werden diese Parameter aktualisiert, sobald ein Nutzer seine Einwilligung erteilt.

Die folgenden <consent_params> werden unterstützt:

Feldname Zulässige Werte
ad_storage 'granted' | 'denied'
analytics_storage 'granted' | 'denied'
wait_for_update beliebige positive Ganzzahl

Parameterbereich

Sie können Parameterwerte auf einzelne Ereignisse, alle Ereignisse, die an ein bestimmtes <TARGET_ID> gesendet werden, oder global auf alle Ereignisse beziehen. Dazu werden die Befehle event, config und set verwendet.

Parameterwerte, die für einen Bereich festgelegt sind, ändern die Werte, die für denselben Parameter in einem anderen Bereich festgelegt wurden, nicht. Im folgenden Beispiel ändert der Befehl config den globalen Wert für currency nicht, der zuvor mit dem Befehl set zugewiesen wurde. Nachdem beide Befehle ausgeführt wurden, lautet der globale Wert von currency immer noch 'EUR'.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

Rangfolge der Parameter

Wenn demselben Parameter in verschiedenen Bereichen unterschiedliche Werte zugewiesen sind, wird bei der Verarbeitung von Ereignissen nur ein einzelner Wert verwendet. Parameterwerte auf event haben Vorrang vor Parametern auf config, und config-Parameter haben Vorrang vor Parametern, die global auf set festgelegt sind.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });