Dokumentacja API tagu Google

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

gtag(<command>, <command parameters>);
  • <command> to jedno z tych poleceń:
  • <command parameters> to parametry, które możesz przekazać do funkcji gtag(). Parametry poleceń różnią się w zależności od polecenia. Więcej informacji znajdziesz w dokumentacji poleceń.

Polecenia gtag() możesz wywoływać w dowolnym miejscu na stronie, o ile pojawiają się one poniżej fragmentu kodu tagu Google. Aby dowiedzieć się, jak dodać fragment kodu do strony, zapoznaj się z przewodnikiem 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 osiągnąć 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 modyfikuje globalnej wartości zmiennej campaign_id przypisanej wcześniej za pomocą polecenia set. Po wykonaniu obu poleceń wartość globalna campaign_id nadal wynosi '1234'.

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

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

Priorytet parametru

Jeśli w różnych zakresach do tego samego parametru są przypisane różne wartości, podczas przetwarzania zdarzeń używana jest tylko jedna wartość. Wartości parametrów w zakresie event mają pierwszeństwo przed parametrami w zakresie config, a parametry w zakresie config mają pierwszeństwo przed parametrami w zakresie globalnym, czyli 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 celów dodatkowych informacji o konfiguracji. Jest to zwykle konfiguracja konkretnej usługi, ale jeśli używasz zarówno Google Ads, jak i Google Analytics, musisz ją skonfigurować tylko raz.

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

Najważniejsze informacje o <TARGET_ID>:

  • Znak <TARGET_ID> w poleceniu gtag('config', <TARGET_ID>, ...) to identyfikator tagu, który określa, gdzie gtag.js ma wysyłać dane o zdarzeniu. Może to być miejsce docelowe, np. usługa w Google Analytics, konto Google Ads, konfiguracja Floodlight lub tag Google, który ma wiele miejsc docelowych.

  • Identyfikator tagu, np. GT-XXXXXX, G-XXXXXX lub AW-YYYYYY, to identyfikator tagu Google. Ten identyfikator dodaje się do kodu witryny, aby wczytać tag Google.

  • Pojedynczy tag Google (identyfikowany przez identyfikator tagu) można skonfigurować tak, aby wysyłał dane do wielu miejsc docelowych. Chociaż niektóre identyfikatory tagów mogą wyglądać identycznie jak identyfikatory miejsc docelowych, np. G-XXXXXX w przypadku usługi w Google Analytics lub AW-YYYYYY w przypadku konta Google Ads, znak <TARGET_ID> w poleceniu config odnosi się do konkretnego wystąpienia tagu Google wczytanego na stronie.

  • Polecenie gtag('config', ...) konfiguruje działanie tagu Google powiązanego z tym konkretnym <TARGET_ID>. Identyfikator tagu w skrypcie src zwykle wczytuje tag Google, ale w poleceniu gtag('config') możesz użyć dowolnego prawidłowego identyfikatora tagu powiązanego z Twoim kontem.

  • Pojedynczy tag Google może mieć wiele powiązanych z nim identyfikatorów tagu, często z powodu scalenia tagów. Dowolny z tych powiązanych identyfikatorów może być użyty w parametrze skryptu src do wczytywania tagu Google.

  • Jeśli wysyłasz dane do wielu miejsc docelowych lub używasz wielu tagów, wystarczy, że w skrypcie src umieścisz tylko jeden fragment kodu tagu Google z jednym identyfikatorem tagu. Następnie dodaj polecenie gtag('config') dla każdego dodatkowego identyfikatora tagu lub miejsca docelowego.

<additional_config_info> to co najmniej 1 para parametr-wartość.

Ten przykład konfiguruje tag tak, aby wysyłał dane na konto Google Ads:

gtag('config', 'TAG_ID');

gdzie „TAG_ID” to identyfikator tagu tagu Google.

Aby pokazać, jak wysyłać dodatkowe informacje o konfiguracji, podajemy przykład, w którym tag jest skonfigurowany tak, aby wysyłać dane na konto Analytics z parametrem send_page_view, który przekazuje wartość false, oraz parametrem groups, który przekazuje wartość 'agency'.

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

get

Umożliwia pobieranie z gtag.js różnych wartości, m.in. ustawianych za pomocą polecenia set.

gtag('get', '<target>', '<field_name>', callback)
Argument Typ Przykład Opis
<target> string G-XXXXXXXXXX

Wartość docelowa, z której mają być pobierane wartości.
<field_name> FieldName client_id Nazwa pola do pobrania.
callback Function (field) => console.log(field)

Funkcja, która będzie wywoływana z odpowiednim polem lub undefined, jeśli nie zostało ono ustawione.

FieldName

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

Nazwa pola Obsługiwane cele
client_id
  • Google Analytics 4
session_id
  • Google Analytics 4
session_number
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Przykłady

Przekazywanie wartości do obiektu Promise 

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

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

Wysyłanie zdarzeń 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 umożliwia zdefiniowanie parametrów, które będą powiązane z każdym kolejnym zdarzeniem na stronie.

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

Możesz na przykład udostępniać parametry kampanii, aby wiele tagów na tej samej stronie miało do nich dostęp.

Poniższy przykład pokazuje, jak ustawić nazwę i identyfikator kampanii na potrzeby wydarzenia zakupowego Czarny Piątek. Ponieważ używasz set, wszystkie inne tagi, np. tagi zdarzeń GA4 lub tagi remarketingu w Google Ads, mogą uzyskiwać dostęp do tych danych.

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

event

Aby wysyłać dane o zdarzeniach, używaj polecenia event.

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

<event_name> to:

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

To polecenie event wywołuje zalecane zdarzenie screen_view z 2 parametrami: app_name i screen_name.

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

Aby skonfigurować wyrażanie zgody, użyj polecenia consent.

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

Więcej informacji o zachowaniu, które konfigurują te parametry, znajdziesz w Centrum pomocy w sekcji dotyczącej zgody użytkowników.

<consent_arg> to 'default' lub 'update'. 'default' służy do ustawiania domyślnych parametrów zgody, które mają być używane, a 'update' służy do aktualizowania tych parametrów, gdy użytkownik wskaże, że wyraża zgodę.

Obsługiwane są te <consent_params>:

Nazwa pola Dozwolone wartości Opis
ad_storage 'granted' | 'denied' Umożliwia przechowywanie danych związanych z reklamami, np. plików cookie (w internecie) lub identyfikatorów urządzeń (w aplikacjach).
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 przypadku witryn lub identyfikatorów aplikacji w przypadku aplikacji) związanych z analityką, np. czasu trwania wizyty.
wait_for_update dowolna dodatnia liczba całkowita, Ustawia czas w milisekundach, przez który należy czekać na wywołanie funkcji aktualizacji uzyskiwania zgody.