Dokumentacja API tagu Google

Interfejs API tagu Google (gtag.js) składa się z jednej funkcji, gtag(), o takim składniku:

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

• <command> to jedno z tych poleceń:
  • config
  • get
  • set
  • event
  • consent
• Parametry <command parameters>, które można przekazywać do usługi gtag(). Parametry poleceń różnią się w zależności od polecenia. Więcej informacji 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, zapoznaj się z przewodnikiem instalacyjnym.

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 poniższym przykładzie polecenie config nie zmienia globalnej wartości parametru campaign_id, która wcześniej została przypisana 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 ograniczone do event mają pierwszeństwo przed parametrami z pola config, a parametry config mają pierwszeństwo przed parametrami z zakresu set o zakresie globalnym.

// 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. Zwykle jest to konfiguracja związana z konkretną usługą, ale jeśli korzystasz zarówno z Google Ads, jak i Google Analytics, wystarczy skonfigurować ją 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

Wykorzystaj obietnicę korzyści

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

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

Poniższy przykład pokazuje, jak skonfigurować nazwę i identyfikator kampanii zakupowej w Czarny Piątek. 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 wysł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 mieć zalecane parametry.
• zdarzenie niestandardowe. Zdarzenie niestandardowe to dowolna utworzona przez Ciebie nazwa zdarzenia z dowolnymi parametrami. Więcej informacji znajdziesz w artykule Konfigurowanie zdarzeń.

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

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

consent

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

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

Więcej informacji o działaniu tych parametrów znajdziesz w artykule dotyczącym zgody na przetwarzanie danych w Centrum pomocy.

<consent_arg> może być równe 'default' lub 'update'. Parametr 'default' służy do ustawiania domyślnych parametrów zgody, które powinny być używane, a parametr 'update' służy do aktualizowania tych parametrów, gdy użytkownik wyrazi zgodę.

Obsługiwane są te <consent_params>: