Google Tag API-Referenz

Die Google-Tag-API (gtag.js) besteht aus einer einzigen 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.

Du kannst gtag()-Befehle überall auf deiner Seite aufrufen, wenn sie unter dem Google-Tag-Snippet angezeigt werden. Informationen zum Hinzufügen des Snippets zu einer Seite finden Sie in der Installationsanleitung.

config

Hier 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 vornehmen, wenn Sie sowohl Google Ads als auch Google Analytics verwenden.

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

<TARGET_ID> ist eine Kennung, die das Ziel für Treffer eindeutig identifiziert, 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 so konfiguriert, dass Daten an ein Google Ads-Konto gesendet werden:

gtag('config', 'TAG_ID');

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

Das folgende Beispiel zeigt, wie Sie zusätzliche Konfigurationsinformationen senden. In diesem Beispiel wird ein Tag so konfiguriert, dass Daten an ein Analytics-Konto mit einem send_page_view-Parameter, der einen Wert von false übergibt, und einem groups-Parameter, der einen Wert von 'agency' übergibt, gesendet werden.

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

get

Ermöglicht das Abrufen verschiedener Werte aus gtag.js, einschließlich der mit dem Befehl set festgelegten Werte.

gtag('get', '<target>', '<field_name>', callback)
Argument Typ Beispiel Beschreibung
<Ziel> string UA-XXXXXXXX-Y

Das Ziel, aus dem Werte abgerufen werden sollen.
<Feldname> Feldname client_id Der Name des abzurufenden Felds.
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 sein, das Sie mit dem Befehl gtag('set') festgelegt haben, oder einen der folgenden Werte:

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

Beispiele

Zu einem Versprechen 

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

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

Ereignis an Measurement Protocol senden 

gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

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

Festgelegten Wert abrufen 

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

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

set

Sie können Werte festlegen, die in allen nachfolgenden gtag()-Aufrufen 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 bestehen bleiben soll. Der folgende Code setzt beispielsweise den Wert von country auf 'US' und den Wert von currency auf 'USD' für alle nachfolgenden Ereignisse auf der Seite:

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 diese 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. Vergleichen Sie die folgenden zwei Beispiele, um dies zu veranschaulichen:

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 wird durch ein Komma getrennt.

Der folgende event-Befehl löst das empfohlene Ereignis screen_view mit zwei Parametern aus: app_name und screen_name.

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

Verwenden Sie den Befehl consent, um die Einwilligung zu 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 Standardparameter für die Einwilligung festgelegt. Außerdem werden 'update' verwendet, um die Parameter zu aktualisieren, sobald ein Nutzer seine Einwilligung erteilt hat.

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 wurden, oder global auf alle Ereignisse anwenden. Dazu werden die Befehle event, config und set verwendet.

Parameterwerte, die in einem Bereich festgelegt sind, haben keine Auswirkungen auf die Werte für denselben Parameter in einem anderen Bereich. 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, ist 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' });

Parameterpriorität

Wenn unterschiedliche Werte demselben Parameter in verschiedenen Bereichen zugewiesen werden, wird bei der Verarbeitung von Ereignissen nur ein einzelner Wert verwendet. Parameterwerte mit dem Status event haben Vorrang vor Parametern mit dem Status config und config-Parameter haben Vorrang vor Parametern, die global set zugewiesen 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>' });