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. Die Befehlsparameter variieren je nach Befehl. Weitere Informationen finden Sie unten in der Befehlsreferenz.

Sie können gtag()-Befehle überall auf Ihrer Seite aufrufen, sofern 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 Ereignisse, die an eine bestimmte <TARGET_ID>, oder global auf alle Ereignisse beschränken. Dazu verwenden Sie die Befehle event, config und set.

Parameterwerte, die in einem Bereich festgelegt wurden, ändern nicht die Werte, die für denselben Parameter in einem anderen Bereich festgelegt wurden. Im folgenden Beispiel ändert der Befehl config den globalen Wert für campaign_id nicht, der zuvor mit dem Befehl set zugewiesen wurde. Nach Ausführung beider Befehle 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' });

Vorrang von Parametern

Wenn demselben Parameter in verschiedenen Bereichen unterschiedliche Werte zugewiesen werden, wird bei der Verarbeitung von Ereignissen nur ein 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 mit set global 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

Hiermit können Sie Zielen zusätzliche Konfigurationsinformationen hinzufügen. In der Regel handelt es sich um eine produktspezifische Konfiguration für ein Produkt. Sie müssen sie 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 Tag-ID, die angibt, wohin gtag.js Ereignisdaten senden soll. Dies kann ein Ziel wie eine Google Analytics-Property oder ein Google Ads-Konto sein oder ein Google-Tag mit mehreren Zielen. <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. Hier wird ein Tag so konfiguriert, dass Daten an ein Analytics-Konto gesendet werden. Es enthält einen send_page_view Parameter, der den Wert false übergibt, und einen groups Parameter, der den Wert 'agency' übergibt.

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 gtag('set') Befehl 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 Kampagnen parameter freigeben, damit sie von mehreren Tags auf derselben Seite aufgerufen werden können.

Im folgenden Beispiel wird ein Kampagnenname und eine Kampagnen-ID für ein Black Friday-Shopping-Ereignis 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 selbst festlegen, 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.

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, das mit diesen Parametern konfiguriert wird, finden Sie in der Hilfe unter Einwilligung.

<consent_arg> ist entweder 'default' oder 'update'. 'default' wird verwendet, um die Standardparameter für die Einwilligung festzulegen, und 'update' wird verwendet, um diese Parameter zu aktualisieren, sobald ein Nutzer seine Einwilligung gibt.

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-IDs (Apps), z.B. zur Besuchsdauer.
wait_for_update Eine beliebige positive Ganzzahl Legt eine Zeit in Millisekunden fest, die auf einen Aufruf zur Aktualisierung der Einwilligung gewartet werden soll.