Das Google-Tag (gtag.js) API besteht aus einer einzelnen Funktion (gtag()
) mit der folgenden Syntax:
gtag(<command>, <command parameters>);
<command>
ist einer der folgenden Befehle:<command parameters>
sind die Parameter, die Sie angtag()
ü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 sie unter dem Google-Tag-Snippet angezeigt werden. Informationen dazu, wie Sie das Snippet einer Seite hinzufügen, finden Sie in der Installationsanleitung.
config
Hierüber können Sie zusätzliche Konfigurationsinformationen zu Zielen hinzufügen. In der Regel ist dies eine produktspezifische Konfiguration für ein Produkt. Sie müssen diese Konfiguration 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 konfiguriert, das Daten an ein Google Ads-Konto sendet:
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. Dazu wird ein Tag konfiguriert, das Daten mit einem send_page_view
-Parameter, der einen Wert von false
übergibt, und einem groups
-Parameter, der einen 'agency'
-Wert an ein Analytics-Konto sendet.
gtag('config', 'TAG_ID', {
'send_page_view': false,
'groups': 'agency'
});
get
Hiermit können Sie verschiedene Werte aus gtag.js
abrufen, einschließlich der Werte, die mit dem Befehl set
festgelegt wurden.
gtag('get', '<target>', '<field_name>', callback)
Argument | Typ | Beispiel | Beschreibung |
---|---|---|---|
<Ziel> | string |
G-XXXXXXXXXX |
Das Ziel, aus dem Werte abgerufen werden sollen. |
<Feldname> | Feldname | client_id | Der Name des abzurufenden Feldes. |
callback | Function |
(field) => console.log(field) |
Eine Funktion, die mit dem angeforderten Feld aufgerufen wird, oder |
Feldname
Der Feldname kann der Name eines benutzerdefinierten Feldes, das Sie mit dem Befehl gtag('set')
festgelegt haben, oder einer der folgenden Werte sein:
Feldname | Unterstützte Ziele |
---|---|
client_id |
|
session_id |
|
gclid |
|
Beispiele
Zusatzversprechen
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...
}
Von Ihnen festgelegten Wert abrufen
gtag('set', {currency: 'USD'});
gtag('get', 'G-XXXXXXXXXX', 'currency', (currency) => {
// Do something with currency value you set earlier.
})
set
Ermöglicht das Festlegen von Werten, die für alle nachfolgenden gtag()
-Aufrufe auf der Seite beibehalten werden.
gtag('set', {<parameter-value-pair>, <parameter-value-pair>});
<parameter-value-pair>
ist ein Schlüsselname und der Wert, der für gtag()
-Aufrufe beibehalten werden soll. Mit dem folgenden Code werden beispielsweise der Wert von country
auf 'US'
und der Wert von currency
auf 'USD'
für alle nachfolgenden Ereignisse auf der Seite festgelegt:
gtag('set', {
'country': 'US',
'currency': 'USD'
});
Der Befehl set
unterscheidet sich von der direkten Übergabe von Werten an den Befehl event
. Wenn Sie Werte direkt an einen event
-Befehl übergeben, gelten sie nur für das ausgelöste Ereignis. Mit set
bleiben die Werte jedoch auf der aktuellen Seite erhalten und werden mit allen nachfolgenden Ereignissen übergeben. Veranschaulichen Sie die folgenden beiden Beispiele:
gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');
und
gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');
Im ersten Beispiel wird das Ereignis login
mit dem Wert method
von 'Google'
und das Ereignis share
ohne Parameter übergeben. Im zweiten Beispiel werden sowohl login
als auch share
mit dem method
-Wert 'Google'
übergeben.
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 mit beliebigen (d.h. benutzerdefinierten) Parametern. Weitere Informationen zur Verwendung von benutzerdefinierten Ereignissen in Google Analytics
<event_params>
ist ein oder mehrere Parameter/Wert-Paare. Jedes Paar ist 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
Mit dem Befehl consent
können Sie die Einwilligung konfigurieren.
gtag('consent', {<consent_arg>}, {<consent_params>});
Weitere Informationen zum Verhalten dieser Parameter finden Sie in der Google Analytics-Hilfe.
<consent_arg>
ist entweder 'default'
oder 'update'
. Mit 'default'
werden die standardmäßigen Einwilligungsparameter 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 |
---|---|
ad_storage |
'granted' | 'denied' |
analytics_storage |
'granted' | 'denied' |
wait_for_update |
beliebige positive Ganzzahl |
Parameterbereich
Sie können Parameterwerte auf einzelne Ereignisse, alle Ereignisse, die an ein bestimmtes <TARGET_ID>
gesendet werden, oder global auf alle Ereignisse beziehen. Dazu werden die Befehle event
, config
und set
verwendet.
Parameterwerte, die für einen Bereich festgelegt sind, ändern die Werte, die für denselben Parameter in einem anderen Bereich festgelegt wurden, nicht. Im folgenden Beispiel ändert der Befehl config
den globalen Wert für currency
nicht, der zuvor mit dem Befehl set
zugewiesen wurde. Nachdem beide Befehle ausgeführt wurden, lautet der globale Wert von currency
immer noch 'EUR'
.
// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });
// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });
Rangfolge der Parameter
Wenn demselben Parameter in verschiedenen Bereichen unterschiedliche Werte zugewiesen sind, wird bei der Verarbeitung von Ereignissen nur ein einzelner Wert verwendet. Parameterwerte auf event
haben Vorrang vor Parametern auf config
, und config
-Parameter haben Vorrang vor Parametern, die global auf set
festgelegt sind.
// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });
// 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>' });