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)

FieldName

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

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.

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

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