Dokumentacja API tagu Google

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

gtag(<command>, <command parameters>);

• <command> to jedno z tych poleceń:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> to parametry, które możesz przekazać do funkcji gtag(). Parametry polecenia różnią się w zależności od polecenia. Informacje o ich dostępnych wartościach znajdziesz poniżej.

Polecenia gtag() możesz wywoływać w dowolnym miejscu na stronie, o ile tylko pojawiają się one pod fragmentem kodu tagu Google. Aby dowiedzieć się, jak dodać fragment kodu do strony, przeczytaj przewodnik instalacji.

Zakres parametru

Wartości parametrów możesz ograniczyć do poszczególnych zdarzeń, wszystkich zdarzeń wysyłanych do określonego <TARGET_ID> lub globalnie do wszystkich zdarzeń. Można to zrobić za pomocą 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 zmienia globalnej wartości parametru campaign_id, który został wcześniej przypisany za pomocą polecenia set. Po wykonaniu obu poleceń globalna wartość campaign_id nadal pozostanie '1234'.

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

Kolejność parametrów

Jeśli temu samemu parametrowi przypisane są różne wartości w różnych zakresach, podczas przetwarzania zdarzeń używana jest tylko jedna wartość. Wartości parametrów ograniczonych do event mają pierwszeństwo przed parametrami ograniczonymi do config, a parametry config mają pierwszeństwo przed parametrami ograniczonymi globalnie za pomocą parametru set.

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

Umożliwia dodawanie do wartości docelowych dodatkowych informacji konfiguracyjnych. Jest to zazwyczaj konfiguracja specyficzna dla usługi, ale jeśli korzystasz zarówno z Google Ads, jak i z Google Analytics, musisz ją skonfigurować tylko raz.

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

<TARGET_ID> to identyfikator, który jednoznacznie identyfikuje docel dla trafień, np. usługę w Google Analytics lub konto Google Ads. <additional_config_info> to co najmniej 1 para parametr-wartość.

W tym przykładzie tag jest skonfigurowany tak, aby wysyłać dane na konto Google Ads:

gtag('config', 'TAG_ID');

gdzie „TAG_ID” to identyfikator tagu Google.

Aby pokazać, jak wysyłać dodatkowe informacje konfiguracyjne, podajemy przykład tagu skonfigurowanego tak, aby wysyłać dane na konto Analytics za pomocą parametru send_page_view, który przekazuje wartość false, oraz parametru groups, który przekazuje wartość 'agency'.

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

get

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

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

Argument	Typ	Przykład	Opis
<target>	string	G-XXXXXXXXXX	Cel, z którego mają zostać pobrane wartości.
<field_name>	FieldName	client_id	Nazwa pola do pobrania.
wywołanie zwrotne	Function	(field) => console.log(field)	Funkcja, która zostanie wywołana z wymaganym polem lub undefined, jeśli nie jest ono ustawione.

FieldName

Nazwa pola może być nazwą pola niestandardowego ustawionego za pomocą polecenia gtag('set')lub jedną z tych wartości:

Nazwa pola	Obsługiwane wartości docelowe
client_id	Google Analytics 4
session_id	Google Analytics 4
gclid	Google Ads Floodlight

Uwaga: jeśli użyjesz polecenia set z tymi nazwami pól, ustawiona przez Ciebie wartość będzie miała pierwszeństwo.

Przykłady

Przekazywanie wartości do obietnicy

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

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

Wysyłanie zdarzenia do Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

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

Pobieranie ustawionej wartości

gtag('set', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

set

Polecenie set pozwala zdefiniować parametry, które będą powiązane z każdym kolejnym zdarzeniem na stronie.

Uwaga: jeśli to możliwe, zalecamy używanie poleceń config lub event.

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

Możesz np. współdzielić parametry kampanii, tak aby dostęp do nich miało wiele tagów na tej samej stronie.

Przykład poniżej pokazuje ustawienie nazwy i identyfikatora kampanii na potrzeby wydarzenia zakupowego Black Friday. Ponieważ używasz tagu set, wszystkie inne tagi, np. tagi zdarzeń GA4 lub tagi remarketingowe Google Ads, mają dostęp do tych danych.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

event

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

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

<event_name> może być:

• Zalecane zdarzenie. Każde zalecane zdarzenie może zawierać zalecane parametry.
• zdarzenie niestandardowe. Zdarzenie niestandardowe to dowolna nazwa zdarzenia, którą możesz wymyślić, z dowolnymi parametrami. Więcej informacji znajdziesz w artykule Konfigurowanie zdarzeń.

<event_params> to co najmniej 1 para parametr-wartość. Każda para jest rozdzielana przecinkiem.

Poniższe polecenie event powoduje wywołanie zalecanego zdarzenia screen_view z 2 parametrami: app_name i screen_name.

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

Ważne: fragment kodu tagu Google musi znajdować się na tej samej stronie, powyżej poleceń event. W przeciwnym razie dane nie zostaną wysłane.

consent

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

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

Więcej informacji o zachowaniu konfigurowanym przez te parametry znajdziesz w Centrum pomocy.

<consent_arg> należy do wartości 'default' lub 'update'. Tag 'default' służy do ustawiania domyślnych parametrów zgody, które należy stosować, a tag 'update' służy do aktualizowania tych parametrów po wyrażeniu przez użytkownika zgody.

Obsługiwane są te wartości <consent_params>:

Nazwa pola	Dozwolone wartości	Opis
ad_storage	'granted' | 'denied'	Umożliwia przechowywanie danych na potrzeby reklam, w tym plików cookie (internetowych) lub identyfikatorów urządzeń (aplikacji).
ad_user_data	'granted' | 'denied'	Określa stan zgody na wysyłanie danych użytkownika do Google w celach reklamowych.
ad_personalization	'granted' | 'denied'	Określa stan zgody na reklamy spersonalizowane.
analytics_storage	'granted' | 'denied'	Umożliwia przechowywanie danych (np. plików cookie w internecie lub identyfikatorów aplikacji) związanych ze statystykami, np. czas trwania wizyty.
wait_for_update	dowolna dodatnia liczba całkowita	Określa czas oczekiwania na wywołanie aktualizacji zgody (w milisekundach).