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

Sie können gtag()-Befehle überall auf Ihrer Seite aufrufen, solange sie unter dem Google-Tag-Snippet angezeigt werden. Weitere 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 werden, oder global auf alle Ereignisse anwenden. Dazu verwenden Sie die Befehle event, config und set.

Parameterwerte, die in einem Gültigkeitsbereich festgelegt werden, ändern die Werte nicht, die für denselben Parameter in einem anderen Gültigkeitsbereich festgelegt wurden. 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 mit dem Gültigkeitsbereich event haben Vorrang vor Parametern mit dem Gültigkeitsbereich config. config-Parameter haben Vorrang vor Parametern, die mit set global festgelegt 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

Hier können Sie Zielen zusätzliche Konfigurationsinformationen hinzufügen. Normalerweise ist das 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 Kennung, mit der das Ziel für Treffer 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 für das Google-Tag.

Im folgenden Beispiel wird gezeigt, wie Sie zusätzliche Konfigurationsinformationen senden. Dabei wird ein Tag konfiguriert, um Daten mit einem send_page_view-Parameter, der den Wert false übergibt, und einem groups-Parameter, der den Wert 'agency' übergibt, an ein Analytics-Konto zu senden.

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

get

Damit können Sie verschiedene Werte von gtag.js abrufen, einschließlich Werte, die mit dem Befehl set festgelegt wurden.

gtag('get', '<target>', '<field_name>', callback)

FieldName

Der Feldname kann der Name eines benutzerdefinierten Felds sein, das Sie mit dem Befehl gtag('set') festgelegt haben, oder einer der folgenden Werte:

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

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 jedem nachfolgenden Ereignis auf der Seite zugeordnet werden.

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

Sie können beispielsweise Kampagnenparameter freigeben, damit über mehrere Tags auf derselben Seite darauf zugegriffen werden kann.

Im Beispiel unten wird gezeigt, 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:

• Ein empfohlenes Ereignis. Für jedes empfohlene Ereignis können empfohlene Parameter verwendet werden.
• Benutzerdefiniertes Ereignis Ein benutzerdefiniertes Ereignis ist ein beliebiger Ereignisname mit beliebigen Parametern, den Sie selbst festlegen. 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'
});

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.

Folgende <consent_params> werden unterstützt: