Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Google Tag API-Referenz

Die Google-Tag API (gtag.js) besteht aus einer einzelnen 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 an einer beliebigen Stelle auf der Seite aufrufen, solange sie unter dem Google-Tag-Snippet stehen. Informationen zum Hinzufügen des Snippets zu einer Seite finden Sie in der Installationsanleitung.

Parameterbereich

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

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

Wenn demselben Parameter in verschiedenen Bereichen unterschiedliche Werte zugewiesen werden, wird bei der Verarbeitung von Ereignissen nur ein einziger Wert verwendet. Parameterwerte, die auf event beschränkt sind, haben Vorrang vor Parametern, die auf config beschränkt sind. Parameter, die auf config beschränkt sind, 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`

Hinweis: Der Befehl gtag('config') wurde verworfen. Verwenden Sie die Google Tag Manager-Benutzeroberfläche, um Tag-Einstellungen und Ziele zu konfigurieren, oder gtag('set'), um In-Page-Parameter festzulegen. Wenn Sie derzeit gtag.js und gtag('config')-Befehle verwenden, müssen Sie Ihre Website nicht neu taggen. Ihre Einrichtung funktioniert weiterhin wie gewohnt.

Warum nehmen wir diese Änderung vor?

Verschiedene Teile der gtag API wurden für eine Zeit entwickelt, in der das Google-Tag keine Benutzeroberfläche hatte und die gesamte Konfiguration als In-Page-Code erfolgen musste. Sie mussten Ihre bevorzugte Konfiguration und die Entscheidungen zum Datenrouting direkt auf Ihrer Website hartcodieren, was es schwieriger machte, die Einstellungen später zu ändern. Durch das Hartcodieren werden diese Einstellungen auch an einen bestimmten Punkt im Lebenszyklus der Seite oder des Ereignisses gebunden. Das erhöht die Komplexität und birgt das Risiko von Race-Bedingungen.

Da das Google-Tag und Google Tag Manager jetzt zusammengeführt wurden, hat jedes Tag eine Benutzeroberfläche. Sie müssen keine Entscheidungen mehr im Voraus treffen oder sie auf Ihrer Website hartcodieren.

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

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

Wichtige Informationen zu <TARGET_ID>:

<TARGET_ID> im Befehl gtag('config', <TARGET_ID>, ...) 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 Websitecode 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 können mit Ziel-IDs identisch sein, 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 der jeweiligen <TARGET_ID> verknüpft ist. Die im Script src enthaltene Tag-ID lädt normalerweise das Google-Tag. Sie können jedoch jede gültige Tag-ID, die mit Ihrem Konto verknüpft ist, im Befehl gtag('config') verwenden.
Ein einzelnes Google-Tag kann mehrere Tag-IDs haben, oft aufgrund der Zusammenführung von Tags. Jede dieser verknüpften IDs kann im Script-Parameter src verwendet werden, um das Google-Tag zu laden.
Wenn Sie Daten an mehrere Ziele senden oder mehrere Tags verwenden, müssen Sie nur ein einzelnes Google-Tag-Snippet mit einer Tag-ID in das Script src einfügen. Anschließend fügen Sie für jede zusätzliche Tag-ID oder jedes zusätzliche Ziel einen gtag('config')-Befehl ein.

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

Hier ist ein Beispiel, wie Sie zusätzliche Konfigurationsinformationen senden können. Es wird ein Tag konfiguriert, um Daten an ein Analytics-Konto zu senden. 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 set-Befehl 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

Beispiele

Wert in ein Promise abrufen

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.

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 werden ein Kampagnenname und eine Kampagnen-ID für ein Black Friday-Shopping-Event festgelegt. 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>: ein oder mehrere Parameter/Wert-Paare. Die Paare werden jeweils durch ein Komma getrennt.

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

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

`consent`

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

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

Weitere Informationen zum Verhalten, das mit diesen Parametern 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 hat.

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 Aufruf zur Aktualisierung der Einwilligung gewartet werden soll.