Interfejs API tagu Google (gtag.js) składa się z 1 funkcji gtag()
o takiej składni:
gtag(<command>, <command parameters>);
<command>
to jedno z tych poleceń:<command parameters>
to parametry, które możesz przekazywać do usługigtag()
. Parametry polecenia różnią się w zależności od polecenia. Więcej informacji znajdziesz w dokumentacji polecenia poniżej.
Polecenia gtag()
możesz wywoływać w dowolnym miejscu na stronie, o ile występują one pod fragmentem kodu tagu Google. Informacje o dodawaniu fragmentu kodu do strony znajdziesz w przewodniku instalacji.
Zakres parametru
Możesz ograniczać wartości parametrów do poszczególnych zdarzeń, wszystkich zdarzeń wysyłanych do określonego elementu <TARGET_ID>
lub globalnie do wszystkich zdarzeń. Użyjesz do tego poleceń event
, config
i set
.
Wartości parametrów ustawione w jednym zakresie nie zmieniają 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
przypisanej wcześniej za pomocą polecenia set
. Po wykonaniu obu poleceń globalna wartość 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' });
Pierwszeństwo parametrów
Jeśli do tego samego parametru w różnych zakresach są przypisane różne wartości, do przetwarzania zdarzeń jest używana tylko jedna wartość. Wartości parametrów z zakresu event
mają pierwszeństwo przed parametrami z zakresu config
, a parametry config
mają pierwszeństwo przed parametrami z zakresu globalnego 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 dodanie do celów dodatkowych informacji o konfiguracji. Zwykle jest to konfiguracja związana z konkretną usługą, ale jeśli używasz zarówno 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 cel działań, np. usługę w Google Analytics czy konto Google Ads.
<additional_config_info>
to co najmniej jedna para parametr–wartość.
Ten przykład pozwala skonfigurować tag do wysyłania danych na konto Google Ads:
gtag('config', 'TAG_ID');
gdzie „ID_TAGU” to identyfikator tagu tagu Google.
Aby zademonstrować, jak wysyłać dodatkowe informacje o konfiguracji, oto przykład konfigurowania tagu do wysyłania danych 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 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 |
Miejsce docelowe, z którego mają być pobierane wartości. |
<nazwa_pola> | FieldName | client_id | Nazwa pola do pobrania. |
wywołanie zwrotne | Function |
(field) => console.log(field) |
Funkcja, która zostanie wywołana z żądanym polem lub |
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 cele |
---|---|
client_id |
|
session_id |
|
gclid |
|
Przykłady
Korzyści z obietnicy
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', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
sendOfflineEvent(clientID, "tutorial_begin")
});
function sendOfflineEvent(clientID, eventName, eventData) {
// Send necessary data to your server...
}
Uzyskiwanie określonej 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. udostępnić parametry campaign, aby wiele tagów na tej samej stronie miało do nich dostęp.
W przykładzie poniżej pokazujemy konfigurowanie nazwy i identyfikatora kampanii związanej z zakupami w Czarny Piątek. Ponieważ używasz metody set
, wszystkie inne tagi, np. tagi zdarzeń GA4 i 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>
to:
- Zalecane zdarzenie. Każde zalecane zdarzenie może przyjmować zalecane parametry.
- Zdarzenie niestandardowe. Zdarzenie niestandardowe to wymyślona przez Ciebie nazwa zdarzenia z dowolnymi (niestandardowymi) parametrami. Zobacz np. sposób użycia zdarzeń niestandardowych w Google Analytics.
<event_params>
to co najmniej jedna 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 konfigurowanym przez te parametry znajdziesz w sekcji dotyczącej zgody w Centrum pomocy.
<consent_arg>
jest jedną z wartości 'default'
lub 'update'
. Parametr 'default'
służy do ustawiania domyślnych parametrów uzyskiwania zgody, a parametr 'update'
służy do ich aktualizowania, gdy użytkownik wyrazi zgodę.
Obsługiwane są te komponenty typu <consent_params>
:
Nazwa pola | Dozwolone wartości | Opis |
---|---|---|
ad_storage |
'granted' | 'denied' |
Umożliwia przechowywanie danych powiązanych z reklamami, np. plików cookie (internet) lub identyfikatorów urządzeń (aplikacje). |
ad_user_data |
'granted' | 'denied' |
Wskazuje zgodę 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 (stron internetowych) lub identyfikatorów aplikacji (aplikacje), związanych z analityką, np. o czasie trwania wizyty. |
wait_for_update |
dowolna dodatnia liczba całkowita | Ustawia czas (w milisekundach) oczekiwania na wywołanie aktualizacji zgody. |