Google Tag API-Referenz

Die Google Tag API (gtag.js) besteht aus der 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 die Befehle unter dem Google-Tag-Snippet angezeigt werden. Informationen zum Hinzufügen des Snippets zu einer Seite finden Sie in der Installationsanleitung.

Parameterbereich

Sie können Parameterwerte auf einzelne Ereignisse, alle Ereignisse, die an eine bestimmte <TARGET_ID> gesendet wurden, oder global auf alle Ereignisse beschränken. Dazu verwenden Sie die Befehle event, config und set.

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

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

Parameterpriorität

Werden einem Parameter in unterschiedlichen Bereichen unterschiedliche Werte zugewiesen, wird bei der Verarbeitung von Ereignissen nur ein einziger Wert verwendet. Parameterwerte mit dem Umfang event haben Vorrang vor Parametern mit dem Umfang config und config-Parameter haben Vorrang vor Parametern mit globaler Ausrichtung mithilfe von set.

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// 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>' });

config

Damit können Sie zusätzliche Konfigurationsinformationen zu Zielen hinzufügen. Normalerweise ist dies eine produktspezifische Konfiguration für ein Produkt. Sie muss jedoch nur einmal konfiguriert werden, 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 Trefferziel 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 so konfiguriert, dass Daten an ein Google Ads-Konto gesendet werden:

gtag('config', 'TAG_ID');

Dabei ist „TAG_ID“ die Tag-ID des Google-Tags.

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

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

get

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

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

Das Ziel, von dem Werte abgerufen werden sollen.

<Feldname> FieldName client_id Der Name des abzurufenden Felds.
callback Function (field) => console.log(field)

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

FieldName

Der Feldname kann der Name eines benutzerdefinierten Felds sein, das Sie mit dem Befehl gtag('set') festgelegt haben, oder einer 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

Wertversprechen für Ihr Angebot nutzen

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...
}

Festgelegten Wert erhalten

gtag('set', {campaign_name: 'Spring_Sale'});

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

set

Mit dem Befehl „set“ können Sie Parameter definieren, die mit jedem nachfolgenden Ereignis auf der Seite verknüpft werden.

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

Sie können beispielsweise Kampagnenparameter freigeben, sodass mehrere Tags auf derselben Seite darauf zugreifen können.

Das folgende Beispiel zeigt, wie Sie einen Kampagnennamen und eine Kampagnen-ID für ein Black-Friday-Shopping-Ereignis festlegen. Da Sie set verwendet haben, können alle anderen Tags, z. B. GA4-Ereignis-Tags oder Google Ads-Remarketing-Tags, auf diese Daten zugreifen.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

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 Hilfe unter consent.

<consent_arg> ist entweder 'default' oder 'update'. 'default' wird verwendet, um die standardmäßigen Einwilligungsparameter festzulegen, die verwendet werden sollen, und 'update' wird verwendet, um diese Parameter zu aktualisieren, sobald ein Nutzer seine Einwilligung erteilt hat.

Die folgenden <consent_params> werden unterstützt:

Feldname Zulässige Werte Beschreibung
ad_storage 'granted' | 'denied' Ermöglicht das Speichern werbebezogener Cookies (Web) oder Geräte-IDs (Apps)
ad_user_data 'granted' | 'denied' Legt die Einwilligung zum Senden von Nutzerdaten zu Werbezwecken an Google fest.
ad_personalization 'granted' | 'denied' Legt die Einwilligung für personalisierte Anzeigen fest
analytics_storage 'granted' | 'denied' Ermöglicht das Speichern analysebezogener Cookies (Web) oder App-IDs (Apps), z. B. Besuchsdauer
wait_for_update beliebige positive Ganzzahl Legt die Zeit in Millisekunden fest, die auf einen Aufruf zur Aktualisierung der Einwilligung gewartet wird.