Jak utworzyć tag serwera

We wprowadzeniu do tagowania po stronie serwera znajdziesz omówienie w Menedżerze tagów tagowania po stronie serwera. Dowiesz się, czym są klienci i co robią: klienci otrzymują dane zdarzeń z urządzeń użytkowników i dostosowują je do użycia przez resztę kontenera. Z tego artykułu dowiesz się, jak przetwarzać te dane w tagach po stronie serwera.

W kontenerze serwera tagi otrzymują przychodzące dane zdarzeń od klientów, przekształcają je i wysyłają z powrotem do zbioru i analizy. Tagi mogą wysyłać dane, dokąd tylko chcesz. Jeśli miejsce docelowe akceptuje żądania HTTP, może też przyjmować dane z kontenera serwera.

Kontenery po stronie serwera mają 3 wbudowane tagi, które są gotowe do użycia bez konieczności konfiguracji niestandardowej:

• Google Analytics 4
• Żądanie HTTP

Jeśli chcesz wysyłać dane do innego miejsca niż Google Analytics lub potrzebujesz więcej funkcji niż zapewnia tag żądania HTTP, musisz użyć innego tagu. Dodatkowe tagi znajdziesz w Galerii szablonów. Możesz też napisać własne. W tym samouczku poznasz podstawy tworzenia własnych tagów dla kontenera serwera.

Cele

• Dowiedz się, których interfejsów API używać do odczytu danych zdarzeń, wysyłania żądań HTTP i ustawiania plików cookie w przeglądarce.
• Poznaj sprawdzone metody konfigurowania opcji tagu.
• Dowiedz się, jaka jest różnica między danymi określonymi przez użytkownika a danymi zbieranymi automatycznie, i dlaczego to rozróżnienie jest ważne.
• Dowiedz się, jaką rolę pełni tag w kontenerze serwera. Dowiedz się, co tag powinien, a czego nie powinien robić.
• Dowiedz się, kiedy warto przesłać szablon tagu do Galerii szablonów społeczności.

Wymagania wstępne

• Wdrożony kontener serwera
• znajomość Menedżera tagów, kontenerów serwera i podstawowych pojęć takich jak klienci, tagi, reguły i zmienne;
• Znajomość podstaw pisania szablonów tagów i zmiennych

Tag Baz Analytics

W tym samouczku utworzysz tag, który wysyła dane pomiarowe do usługi o nazwie Baz Analytics.

Baz Analytics to prosta, hipotetyczna usługa analityczna, która pozyskuje dane za pomocą żądań HTTP GET do usługi https://example.com/baz_analytics. Zawiera on te parametry:

Parametr	Przykład	Opis
id	BA-1234	identyfikator Twojego konta Baza Analytics.
en	click	Nazwa zdarzenia.
L	https://www.google.com/search?q=sgtm	Adres URL strony, na której wystąpiło zdarzenie.
U	2384294892	Identyfikator użytkownika, który wykonał działanie. Służy do przypisywania wielu działań do jednego użytkownika.

Konfiguracja tagu

Najpierw utwórz szablon tagu. Otwórz w kontenerze sekcję Szablony i w sekcji Szablony tagów kliknij Nowy. Dodaj nazwę i opis tagu.

Następnie w sekcji Pola w edytorze szablonów dodaj różne opcje konfiguracji tagu. Kolejne oczywiste pytanie brzmi: jakich opcji potrzebujesz? Tag możesz utworzyć na 3 sposoby:

1. Łączna konfiguracja: dodaj pole konfiguracji dla każdego parametru. Wymagaj od użytkownika skonfigurowania wszystkich ustawień.
2. Brak konfiguracji: nie masz żadnych opcji konfiguracji tagu. Wszystkie dane są pobierane bezpośrednio ze zdarzenia.
3. Niektóre konfiguracje: zawierają pola tylko dla niektórych parametrów.

Dzięki możliwości stosowania pól dla każdego parametru użytkownik ma pełną kontrolę nad konfiguracją tagu. W praktyce zwykle skutkuje to jednak dużą liczbą powielonych treści. W szczególności takie elementy jak parametr Baz Analytics l, który zawiera adres URL strony, są jednoznaczne i uniwersalne. Wpisywanie tych samych, niezmiennych danych za każdym razem, gdy konfigurujesz tag, to zadanie dla komputera.

Może rozwiązaniem jest użycie tagu, który pobiera dane tylko z zdarzenia. To najprostszy tag do skonfigurowania, ponieważ nie wymaga od użytkownika żadnego działania. Z drugiej strony jest też najbardziej restrykcyjny i niestabilny. Użytkownicy nie mogą zmieniać działania tagu, nawet jeśli jest to konieczne. Na przykład w witrynie i w Google Analytics zdarzenie może się nazywać purchase, ale w usłudze Baz Analytics – buy. Może też być tak, że założenia tagu dotyczące struktury przychodzących danych o zdarzeniu nie odpowiadają rzeczywistości. W obu przypadkach użytkownik utknie.

Jak w przypadku wielu innych rzeczy, odpowiedź leży gdzieś pomiędzy tymi skrajnościami. Niektóre dane warto zawsze pobierać z wydarzenia. Pozostałe dane powinien skonfigurować użytkownik. Jak decydujesz, które jest które? Aby odpowiedzieć na to pytanie, musimy dokładniej przyjrzeć się danym przesyłanym do kontenera.

Skąd pochodzą dane?

Dane trafiające do kontenera serwera z tagu Google Analytics 4 można w przybliżeniu podzielić na 2 kategorie: dane określone przez użytkownika i dane zbierane automatycznie.

Dane określone przez użytkownika to wszystko, co użytkownik umieszcza w komendach gtag.js event. Na przykład polecenie:

gtag('event', 'search', {
  search_term: 'beets',
});

W kontenerze serwera pojawią się te parametry:

{
  event_name: 'search',
  search_term: 'beets',
}

To proste, ale z perspektywy tagu bardzo trudno się nim pracować. Ponieważ te dane są wprowadzane przez użytkownika, mogą być dowolne. Być może, jak w przypadku powyżej, użytkownik wysyła tylko zalecane zdarzenia i ich parametry, ale nie jest to wymagane. Z ważnym wyjątkiem lokalizacji (ale nie wartości!) parametru event_name nie ma gwarancji co do formy ani struktury danych użytkownika.

Na szczęście kontener nie będzie otrzymywać tylko danych wprowadzonych przez użytkownika. Usługa ta będzie też otrzymywać wiele danych, które są automatycznie zbierane przez tag Google Analytics 4 w przeglądarce. Źródła te obejmują:

• ip_override
• language
• page_location
• page_referrer
• page_title
• screen_resolution
• user_agent

Jeśli żądanie serwera pochodzi z przeglądarki internetowej, dane z plików cookie przeglądarki mogą być dostępne przez interfejs API getCookieValue.

Razem tworzą one wspomniane wcześniej dane zbierane automatycznie. Ogólnie są to dane, które są uniwersalne i jednoznaczne pod względem semantycznym. Gdy żądanie przychodzi w przeglądarce z tagu GA4, dane te będą zawsze dostępne i zawsze będą mieć ten sam format. Więcej informacji o tych parametrach znajdziesz w materiałach dotyczących zdarzeń.

Ta klasyfikacja jest przydatnym narzędziem, które pomaga nam określić, które dane powinien skonfigurować użytkownik, a które należy podać w tagu. Dane zbierane automatycznie można bezpiecznie odczytać bezpośrednio ze zdarzenia. Pozostałe ustawienia powinien skonfigurować użytkownik.

Mając to na uwadze, przyjrzyj się jeszcze raz parametrom tagu Baz Analytics.

• Identyfikator pomiaru:id ponieważ nie jest on zbierany automatycznie, jest to wyraźny przykład wartości, którą użytkownik powinien wpisać podczas konfigurowania tagu.
• Nazwa zdarzenia, en: jak wspomniano powyżej, nazwę zdarzenia można zawsze pobrać bezpośrednio z parametru event_name. Ponieważ jednak jego wartość jest zdefiniowana przez użytkownika, warto udostępnić możliwość zastąpienia nazwy w razie potrzeby.
• URL strony, l: tę wartość można pobrać z parametru page_location, który jest automatycznie zbierany przez tag przeglądarki Google Analytics GA4 w przypadku każdego zdarzenia. Dlatego nie wymagaj od użytkownika ręcznego wpisywania wartości.
• Identyfikator użytkownika, u: w tagu serwera Baz Analytics parametr u nie jest określony przez użytkownika ani nie jest zbierany automatycznie przez tag na stronie. Jest on przechowywany w pliku cookie przeglądarki, aby można było zidentyfikować użytkowników podczas kolejnych wizyt w witrynie. Jak widać w implementacji poniżej, jest to tag serwera Baz Analytics, który ustawia plik cookie za pomocą interfejsu API setCookie. Oznacza to, że tylko tag Baz Analytics wie, gdzie i jak jest przechowywany plik cookie. Podobnie jak w przypadku parametru l, parametr u powinien być zbierany automatycznie.

Gdy skończysz konfigurować tag, powinien wyglądać mniej więcej tak:

Implementacja tagów

Po skonfigurowaniu tagu możesz przejść do implementowania jego działania w JavaScript w trybie piaskownicy.

Tag musi spełniać 4 kryteria:

1. Pobierz nazwę zdarzenia z konfiguracji tagu.
2. Pobierz adres URL strony z właściwości page_location zdarzenia.
3. Oblicz identyfikator użytkownika. Tag będzie szukać identyfikatora użytkownika w pliku cookie o nazwie _bauid. Jeśli go nie ma, tag obliczy nową wartość i zapisze ją na potrzeby późniejszych żądań.
4. Utwórz adres URL i wyślij żądanie do serwera kolekcji Baz Analytics.

Warto też zastanowić się, jak tag pasuje do kontenera jako całości. Różne komponenty kontenera pełnią różne role, dlatego tag nie może lub nie powinien wykonywać pewnych czynności. Tag:

• Nie musi sprawdzać zdarzenia, aby ustalić, czy powinno ono zostać wykonane. Do tego służy wyzwalacz.
• Nie należy uruchamiać kontenera za pomocą interfejsu API runContainer. To zadanie klienta.
• Z ważnym wyjątkiem plików cookie nie powinien on wchodzić w bezpośrednią interakcję z żądaniem ani odpowiedzią. To też zadanie klienta.

Utworzenie szablonu tagu, który wykonuje którekolwiek z tych działań, może spowodować niejasne działanie dla użytkowników tagu. Na przykład tag, który wysyła odpowiedź na żądanie przychodzące, uniemożliwi klientowi wykonanie tej czynności. Przekonałoby to użytkowników o tym, jak powinien działać kontener.

Poniżej znajdziesz opatrzoną adnotacjami implementację tagu w sandboksie JS.

const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');

const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;

// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');

// page_location is automatically collected by the Google Analytics 4 tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();

const url = 'https://www.example.com/baz_analytics?' +
    'id=' + encodeUriComponent(data.measurementId) +
    'en=' + encodeUriComponent(eventName) +
    (pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
    'u=' + userId;

// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
  if (result.statusCode >= 200 && result.statusCode < 300) {
    data.gtmOnSuccess();
  } else {
    data.gtmOnFailure();
  }
});

// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
  const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
  // The setCookie API adds a value to the 'cookie' header on the response.
  setCookie(USER_ID_COOKIE, makeString(userId), {
    'max-age': 3600 * 24 * 365 * 2,
    domain: 'auto',
    path: '/',
    httpOnly: true,
    secure: true,
  });

  return userId;
}

Tag został zaimplementowany. Zanim użyjesz tagu, musisz odpowiednio skonfigurować jego uprawnienia API. Na karcie Uprawnienia w Edytorze szablonów określ te uprawnienia:

• Odczyt wartości plików cookie: _bauid
• Odczyt danych zdarzenia: event_name i page_location
• Wysyła żądania HTTP: https://www.example.com/*
• Ustawia plik cookie: _bauid

Należy też napisać test tagu. Więcej informacji o testowaniu szablonów znajdziesz w sekcji testy w przewodniku dla deweloperów dotyczącym szablonów.

Na koniec pamiętaj, aby co najmniej raz uruchomić tag za pomocą przycisku Uruchom kod. Zapobiegnie to popełnieniu wielu prostych błędów na serwerze.

Przesyłanie tagu do Galerii szablonów społeczności

Masz już za sobą wszystkie czynności związane z tworzeniem, testowaniem i wdrażaniem nowego tagu, więc nie ma powodu, by zachowywać się wyłącznie dla Ciebie. Jeśli uważasz, że nowy tag będzie przydatny dla innych osób, prześlij go do Galerii szablonów społeczności.

Podsumowanie

Z tego samouczka dowiesz się, jak pisać tagi dla kontenera serwera. Wiesz już:

• interfejsów API, które mają być używane do odczytywania danych zdarzeń, wysyłania żądań HTTP i umieszczania plików cookie w przeglądarce.
• Sprawdzone metody projektowania opcji konfiguracji tagu.
• Różnica między danymi określonymi przez użytkownika a danymi zbieranymi automatycznie oraz dlaczego to rozróżnienie jest ważne.
• Rola tagu w kontenerze, czyli to, co powinien i czego nie powinien robić.
• Kiedy i jak przesyłać szablony tagów do Galerii szablonów społeczności.