Dokumentacja API tagu Google

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

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(). Polecenie parametry różnią się w zależności od polecenia. znajdziesz w materiałach dotyczących poleceń, poniżej.

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

Zakres parametru

Wartości parametrów możesz ograniczać do poszczególnych zdarzeń, wszystkich zdarzeń wysyłanych do <TARGET_ID> lub globalnie do wszystkich zdarzeń. Jest to możliwe dzięki zastosowaniu polecenia event, config i set.

Wartości parametrów ustawione w jednym zakresie nie modyfikują wartości ustawionych dla tego samego zakresu w innym zakresie. W poniższym przykładzie polecenie config nie modyfikuj wartości globalnej dla campaign_id przypisanej wcześniej za pomocą funkcji set . Po wykonaniu obu poleceń globalna wartość campaign_id 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 przypisano różne wartości, tylko do przetwarzania zdarzeń jest używana jedna wartość. Wartości parametrów ograniczone do Parametr event będzie miał pierwszeństwo przed parametrami ograniczonymi do config i config mają pierwszeństwo przed parametrami o zakresie globalnym określonym w parametrze 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. To jest zwykle jest to konfiguracja dla konkretnego produktu, ale wystarczy skonfiguruj je raz, jeśli korzystasz zarówno z Google Ads, jak i z Google Analytics.

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

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

Ten przykład konfiguruje tag, który wysyła dane na konto Google Ads:

gtag('config', 'TAG_ID');

gdzie „TAG_ID” to identyfikator tagu Google.

Aby pokazać, jak wysłać dodatkowe informacje o konfiguracji, zapoznaj się z przykładem. konfiguruje tag, który wysyła dane na konto Analytics z tagiem Parametr send_page_view, który przekazuje wartości false i groups , który przekazuje wartość 'agency'.

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

get

Umożliwia uzyskanie różnych wartości z metody gtag.js, w tym wartości ustawionych za pomocą parametru 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, które ma zostać pobrane.
wywołanie zwrotne	Function	(field) => console.log(field)	funkcję, która zostanie wywołana z żądanym polem, lub undefined, jeśli nie jest skonfigurowana.

FieldName

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

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

Uwaga: jeśli używasz polecenia set z tymi nazwami pól, ustawiona wartość będą miały pierwszeństwo.

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 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 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 kolejne zdarzenie 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 na przykład udostępnić kampanię tak, by dostęp do nich miało wiele tagów na tej samej stronie.

Poniższy przykład pokazuje ustawianie nazwy i identyfikatora kampanii na Czarny Piątek zakupowego. Używasz już tagu set, więc wszystkie inne tagi, np. Do tych danych mają dostęp tagi zdarzeń GA4 i tagi remarketingowe Google Ads.

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 rekomendowane zdarzenie może potrwać parametry zalecane.
• Zdarzenie niestandardowe. Zdarzenie niestandardowe to dowolna wybrana przez Ciebie nazwa zdarzenia, z dowolnymi (np. niestandardowymi) parametrami. Na przykład zobacz wykorzystania w Google Analytics zdarzeń niestandardowych.

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

Następujące polecenie event uruchamia zalecane zdarzenie screen_view z 2 wartościami parametry: 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 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 tych użytkowników znajdziesz w artykule dotyczącym zgody w Centrum pomocy. .

<consent_arg> należy do wartości 'default' lub 'update'. Pole 'default' jest używane do ustawiania domyślne parametry zgody, których należy używać, a zasada 'update' służy do: aktualizować te parametry, gdy użytkownik wyrazi zgodę.

Obsługiwane są te <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 (internetowych) lub identyfikatorów aplikacji (aplikacji), dotyczących statystyk, np. długość wizyty.
wait_for_update	dowolna dodatnia liczba całkowita	Określa czas oczekiwania na wywołanie aktualizacji zgody (w milisekundach).