Dokumentacja interfejsu API tagów Google

Interfejs API tagu Google (gtag.js) składa się z 1 funkcji o następującej składni: gtag()

gtag(<command>, <command parameters>);
  • <command> to jedno z tych poleceń:
  • <command parameters> to parametry, które możesz przekazywać do funkcji gtag(). Parametry polecenia zależą od polecenia. Więcej informacji znajdziesz w poniższym poleceniu.

Polecenia gtag() mogą być wywoływane w dowolnym miejscu na stronie, jeśli polecenia są widoczne pod fragmentem kodu tagu Google. Aby dowiedzieć się, jak dodać fragment kodu do strony, zajrzyj do przewodnika instalacji.

config

Pozwala dodawać dodatkowe informacje o konfiguracji do celów. Jest to zwykle konfiguracja konkretnej usługi, ale można to zrobić tylko raz, jeśli używasz Google Ads i Google Analytics.

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

<TARGET_ID> to unikalny identyfikator celu działań, np. usługa Google Analytics lub konto Google Ads. <additional_config_info> to co najmniej jedna para parametr-wartość.

Ten przykład konfiguruje tag do wysyłania danych na konto Google Ads:

gtag('config', 'TAG_ID');

gdzie „ID_TAGU” to identyfikator tagu tagu Google.

Aby pokazać, jak przesłać dodatkowe informacje konfiguracyjne, zobacz przykład konfigurowania tagu w taki sposób, aby wysyłał dane na konto Analytics z parametrem send_page_view, który przekazuje wartość false, oraz parametr groups, który przekazuje wartość 'agency'.

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

get

Umożliwia pobieranie różnych wartości od gtag.js, w tym wartości ustawionych za pomocą polecenia set.

gtag('get', '<target>', '<field_name>', callback)
Argument Typ Przykład Opis
<cel> string UA-XXXXXXXX-Y;

Cel, z którego mają być pobierane wartości.
<nazwa_pola> Nazwa pola client_id Nazwa pola do pobrania.
wywołanie zwrotne Function (field) => console.log(field)

Funkcja, która będzie wywoływana z polem wymaganym lub undefined, jeśli nie zostanie ustawiona.

Nazwa pola

Nazwa pola może być nazwą pola niestandardowego podanego przez polecenie gtag('set') lub jedną z tych wartości:

Nazwa pola Obsługiwane cele
client_id
  • Google Analytics 4
  • Universal Analytics (Google Analytics)
session_id
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Przykłady

Obiecaj obietnicę 

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Wysyłanie zdarzenia do platformy Measurement Protocol 

gtag('get', 'UA-XXXXXXXX-Y', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Uzyskaj wartość 

gtag('set', {currency: 'USD'});

gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

set

Umożliwia ustawienie wartości, które pozostają aktywne we wszystkich kolejnych wywołaniach gtag() na stronie.

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

<parameter-value-pair> to nazwa klucza i wartość, która zostanie zapisana w gtag() wywołaniach. Na przykład poniższy kod ustawia wartość country na 'US', a wartość currency na 'USD' dla wszystkich kolejnych zdarzeń na stronie:

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

Użycie polecenia set różni się od przekazywania wartości bezpośrednio do polecenia event. Gdy przekazujesz wartości bezpośrednio do polecenia event, odnoszą się one tylko do wywoływanego zdarzenia. W przypadku set wartości są zachowywane na bieżącej stronie i przekazywane razem ze wszystkimi kolejnymi zdarzeniami. Dla zilustrowania tego 2 przykładów:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

i

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

W pierwszym przykładzie zdarzenie login będzie przekazywane z wartością method 'Google', a zdarzenie share będzie przekazywane bez parametrów. W drugim przykładzie zarówno login, jak i share zostaną przekazane z wartością method o wartości 'Google'.

event

Aby wysłać dane zdarzenia, użyj polecenia event.

gtag('event', '<event_name>', {<event_params>});

<event_name> to:

<event_params> to co najmniej jedna para parametr-wartość. Każda para jest oddzielona przecinkami.

To polecenie event uruchamia zalecane zdarzenie screen_view z 2 parametrami: app_name i screen_name.

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

Aby skonfigurować zgodę, użyj polecenia consent.

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

Więcej informacji o zachowaniu tych parametrów znajdziesz w artykule zgoda w Centrum pomocy.

<consent_arg> może mieć wartość 'default' lub 'update'. Parametr 'default' jest używany do ustawienia domyślnych parametrów zgody, które mają być używane, a 'update' służy do ich aktualizacji po udzieleniu zgody przez użytkownika.

Obsługiwane są te atrybuty <consent_params>:

Nazwa pola Dozwolone wartości
ad_storage 'granted' | 'denied'
analytics_storage 'granted' | 'denied'
wait_for_update dowolna dodatnia liczba całkowita

Zakres parametrów

Możesz określić zakresy parametrów dla poszczególnych zdarzeń, wszystkich zdarzeń wysyłanych do konkretnego zdarzenia <TARGET_ID> lub globalnie do wszystkich zdarzeń. Aby to zrobić, użyj poleceń event, config i set.

Wartości parametrów ustawione w jednym zakresie nie modyfikują wartości ustawionych dla tego samego parametru w innym zakresie. W przykładzie poniżej polecenie config nie modyfikuje wartości globalnej dla elementu currency przypisanego wcześniej za pomocą polecenia set. Po wykonaniu obu poleceń globalna wartość currency nadal wynosi 'EUR'.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

Pierwszeństwo parametrów

Jeśli do tego samego parametru w różnych zakresach są przypisane różne wartości, podczas przetwarzania zdarzeń używana jest tylko jedna wartość. Wartości parametrów z zakresu event mają pierwszeństwo przed parametrami o zakresie config i parametrami config mają pierwszeństwo przed parametrami o zakresie globalnym zdefiniowanym w zasadzie set.

// 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>' });