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:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> sind die Parameter, die Sie an gtag() übergeben können. Die Befehlsparameter variieren je nach Befehl. Weitere Informationen finden Sie in der Befehlsreferenz.

Sie können gtag()-Befehle überall auf Ihrer Seite aufrufen, sofern sie unter dem Google-Tag-Snippet stehen. Installationsanleitung

Parameterbereich

Sie können Parameterwerte auf einzelne Ereignisse, alle Ereignisse, die an eine bestimmte <TARGET_ID> gesendet werden, oder global auf alle Ereignisse eingrenzen. Dies wird durch die Verwendung der Befehle event, config und set erreicht.

Parameterwerte, die in einem Bereich festgelegt sind, ändern nicht die Werte, die für denselben Parameter in einem anderen Bereich festgelegt sind. Im folgenden Beispiel wird der globale Wert für campaign_id, der zuvor mit dem Befehl set zugewiesen wurde, durch den Befehl config nicht geändert. Nachdem beide Befehle ausgeführt wurden, ist der globale Wert von campaign_id weiterhin '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

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

// 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

Ermöglicht das Hinzufügen zusätzlicher Konfigurationsinformationen zu Zielen. Dies ist in der Regel eine produktspezifische Konfiguration für ein Produkt. Wenn Sie sowohl Google Ads als auch Google Analytics verwenden, müssen Sie sie jedoch nur einmal konfigurieren.

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

Wichtige Punkte zu <TARGET_ID>:

• Die <TARGET_ID> im gtag('config', <TARGET_ID>, ...)-Befehl ist eine Tag-ID, die angibt, wohin gtag.js Ereignisdaten senden soll. Das kann ein Ziel wie eine Google Analytics-Property, ein Google Ads-Konto, eine Floodlight-Konfiguration oder ein Google-Tag mit mehreren Zielen sein.

• Eine Tag-ID, z. B. GT-XXXXXX, G-XXXXXX oder AW-YYYYYY, ist eine Kennung für Ihr Google-Tag. Sie fügen diese ID in den Code Ihrer Website ein, um das Google-Tag zu laden.

• Ein einzelnes Google-Tag (identifiziert durch seine Tag-ID) kann so konfiguriert werden, dass Daten an mehrere Ziele gesendet werden. Einige Tag-IDs sehen möglicherweise identisch mit Ziel-IDs aus, z. B. G-XXXXXX für eine Google Analytics-Property oder AW-YYYYYY für ein Google Ads-Konto. Die <TARGET_ID> im config-Befehl bezieht sich jedoch auf die jeweilige Instanz des Google-Tags, das auf der Seite geladen wird.

• Mit dem Befehl gtag('config', ...) wird das Verhalten des Google-Tags konfiguriert, das mit diesem bestimmten <TARGET_ID> verknüpft ist. Mit der Tag-ID im Script src wird in der Regel das Google-Tag geladen. Sie können aber auch eine beliebige gültige Tag-ID verwenden, die mit Ihrem Konto verknüpft ist.gtag('config')

• Einem einzelnen Google-Tag können mehrere Tag-IDs zugeordnet sein, was häufig auf das Zusammenführen von Tags zurückzuführen ist. Jede dieser verknüpften IDs kann im src-Parameter des Skripts verwendet werden, um das Google-Tag zu laden.

• Wenn Sie Daten an mehrere Ziele senden oder mehrere Tags verwenden, müssen Sie nur ein Google-Tag-Snippet mit einer Tag-ID im Script src einfügen. Fügen Sie dann für jede zusätzliche Tag-ID oder jedes zusätzliche Ziel ein gtag('config')-Befehl ein.

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

Im folgenden Beispiel wird gezeigt, wie zusätzliche Konfigurationsinformationen gesendet werden. Ein Tag wird so konfiguriert, dass Daten an ein Analytics-Konto gesendet werden. Dabei wird ein send_page_view-Parameter mit dem Wert false und ein groups-Parameter mit dem Wert 'agency' übergeben.

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

get

Hiermit können Sie verschiedene Werte aus gtag.js abrufen – einschließlich Werten, 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
<field_name>	FieldName	client_id	Der Name des Feldes, das abgerufen werden soll
callback	Function	(field) => console.log(field)	Eine Funktion, die mit dem angeforderten Feld aufgerufen wird, oder undefined, wenn nichts 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
session_id	Google Analytics 4
session_number	Google Analytics 4
gclid	Google Ads Floodlight

Hinweis :Wenn Sie den Befehl set mit diesen Feldnamen verwenden, hat der von Ihnen festgelegte Wert Vorrang.

Beispiele

Wert in ein Promise einfügen

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

Einen von Ihnen festgelegten Wert abrufen

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.

Hinweis :Wir empfehlen, wenn möglich die Befehle config oder event zu verwenden.

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

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

Im folgenden Beispiel wird gezeigt, wie Sie einen Kampagnennamen und eine Kampagnen-ID für ein Black Friday-Shopping-Event 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:

• Ein empfohlenes Ereignis. Für jedes empfohlene Ereignis können empfohlene Parameter verwendet werden.
• Ein benutzerdefiniertes Ereignis. Ein benutzerdefiniertes Ereignis ist ein beliebiger Ereignisname, den Sie sich ausdenken, mit beliebigen Parametern. Weitere Informationen finden Sie unter Ereignisse einrichten.

<event_params> ist ein oder mehrere Parameter/Wert-Paare. Jedes Paar wird 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'
});

Wichtig :Das Google-Tag-Snippet muss auf derselben Seite über event-Befehlen stehen, da Ihre Daten sonst nicht gesendet werden.

consent

Verwenden Sie den Befehl consent, um die Einwilligung zu konfigurieren.

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

Weitere Informationen zum Verhalten, das durch diese Parameter konfiguriert wird, finden Sie in der Hilfe unter Einwilligung.

<consent_arg> ist entweder 'default' oder 'update'. Mit 'default' werden die Standardparameter für die Einwilligung 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	Beschreibung
ad_storage	'granted' | 'denied'	Ermöglicht das Speichern von werbebezogenen Daten wie Cookies (Web) oder Geräte-IDs (Apps).
ad_user_data	'granted' | 'denied'	Legt die Einwilligung für das 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 von analysebezogenen Daten wie Cookies (Web) oder App-Kennungen (Apps), z.B. zur Besuchsdauer.
wait_for_update	Beliebige positive Ganzzahl	Legt eine Zeit in Millisekunden fest, die auf einen Einwilligungsaktualisierungsaufruf gewartet werden soll.