Jak utworzyć tag serwera

W artykule Wprowadzenie do tagowania po stronie serwera znajdziesz omówienie tagowania po stronie serwera w Menedżerze tagów. Wiesz już, czym są klienty i do czego służą: otrzymują dane zdarzeń z urządzeń użytkowników i dostosowują je do wykorzystania w pozostałej części kontenera. Z tego artykułu dowiesz się, jak przetwarzać te dane w tagach po stronie serwera.

W kontenerze serwera tagi odbierają przychodzące dane zdarzeń od Twoich klientów, przekształcają je i wysyłają z powrotem do zbierania i analizy. Tagi mogą wysyłać dane w dowolne miejsce. O ile miejsce docelowe akceptuje żądania HTTP, może też akceptować dane z kontenera serwera.

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

• Google Analytics 4
• Google Analytics – Universal Analytics
• Żądanie HTTP

Jeśli chcesz wysyłać dane do innych źródeł 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, ale możesz też tworzyć własne tagi. W tym samouczku poznasz podstawy tworzenia własnych tagów dla kontenera serwera.

Cele

• Dowiedz się, których interfejsów API używać do odczytywania danych o zdarzeniach, wysyłania żądań HTTP i umieszczania plików cookie w przeglądarce.
• Poznaj sprawdzone metody projektowania opcji konfiguracji tagu.
• Dowiedz się, na czym polega różnica między danymi określonymi przez użytkowników a danymi zbieranymi automatycznie. Dowiedz się też, dlaczego jest to tak ważne.
• Poznaj rolę tagu w kontenerze serwera. Dowiedz się, co tag powinien, a co nie.
• Dowiedz się, kiedy warto przesłać szablon tagu do Galerii szablonów.

Wymagania wstępne

• Wdrożony kontener serwera
• znajomość Menedżera tagów, kontenerów serwera i podstawowych zagadnień, takich jak klienty, tagi, reguły i zmienne;
• Wiedza z podstawami pisania szablonów tagów i zmiennych.

Tag Analytics w usłudze Baza

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

Baza Analytics to prosta, hipotetyczna usługa analityczna, która pozyskuje dane za pomocą żądań HTTP GET wysyłanych do usługi https://example.com/baz_analytics. Ma następujące parametry:

Parametr	Przykład	Opis
id	BA-1234	Identyfikator Twojego konta Analytics.
angielski	click	Nazwa zdarzenia.
L	https://www.google.com/search?q=sgtm	URL strony, na której wystąpiło zdarzenie.
U	2384294892	Identyfikator użytkownika wykonującego działanie. Służy do powiązania wielu działań z jednym użytkownikiem.

Konfiguracja tagu

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

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

1. Łączna konfiguracja: dla każdego parametru dodaj pole konfiguracji. Wymagaj od użytkownika wyraźnego ustawienia wszystkich danych.
2. Brak konfiguracji: brak dostępnych opcji konfigurowania tagu. Wszystkie dane są pobierane bezpośrednio ze zdarzenia.
3. Pewna konfiguracja: zawiera pola tylko dla niektórych parametrów,

Pola każdego parametru są bardzo elastyczne i zapewniają użytkownikowi pełną kontrolę nad konfiguracją tagów. W praktyce powstaje zwykle wiele powielonych treści. Parametr l Baza Analytics, który zawiera adres URL strony, są jednoznaczne i uniwersalne. Najlepiej pozostawić komputerowi te same, niezmienne dane za każdym razem, gdy tag jest skonfigurowany.

Być może warto mieć tag, który pobiera dane tylko ze zdarzenia. Jest to najprostszy tag, który użytkownik może skonfigurować, ponieważ nie wymaga żadnych działań. Z drugiej strony jest też najbardziej restrykcyjną i najbardziej delikatną opcją. Użytkownicy nie mogą zmieniać działania tagu, nawet jeśli muszą. Na przykład mogą wywołać zdarzenie purchase na swojej stronie i w Google Analytics, a w Bazie Analytics – buy. A może założenia przyjęte przez tag dotyczące struktury przychodzących danych zdarzenia nie zgadzają się z rzeczywistością. W obu przypadkach użytkownik utknie.

Tak jak w wielu innych sytuacjach, odpowiedź leży gdzieś między dwoma skrajnościami. Niektóre dane zawsze są pobierane ze zdarzenia. Inne dane powinien skonfigurować użytkownik. Jak decydujecie, który jest który? Aby odpowiedzieć na to pytanie, przyjrzymy się danym wpływającym do kontenera.

Skąd pochodzą dane?

Dane przekazywane z tagu Google Analytics 4 do kontenera serwera można podzielić na 2 kategorie: dane określone przez użytkowników i dane zbierane automatycznie.

Dane określone przez użytkownika to wszystko, co użytkownik umieszcza w poleceniu event w tagu gtag.js. Możesz na przykład użyć tego polecenia:

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

Spowoduje to zwrócenie w kontenerze serwera tych parametrów:

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

To dość proste, ale z punktu widzenia tagu jest bardzo trudne. Wprowadzane przez użytkownika dane mogą być dowolne. Być może tak jak powyżej użytkownik wysyła tylko zalecane zdarzenia i parametry, ale nie jest to wymagane. Z wyjątkiem lokalizacji (ale nie wartości) parametru event_name nie ma żadnych gwarancji dotyczących formy ani struktury danych użytkownika.

Na szczęście dane wprowadzone przez użytkownika nie są jedyną rzeczą, którą dany kontener otrzyma. Znajdzie się w nim też zbiór danych, które są automatycznie zbierane w przeglądarce przez tag Google Analytics 4. Źródła te obejmują:

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

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

Łącznie składają się one na dane zbierane automatycznie, o których wspomnieliśmy wyżej. Ogólnie rzecz biorąc, składa się z danych, które są uniwersalne i jednoznaczne pod względem semantycznym. Gdy w przeglądarce pochodzi żądanie z tagu GA4, dane te zawsze będą dostępne i będą mieć zawsze ten sam format. Więcej informacji o tych parametrach znajdziesz w dokumentacji zdarzeń.

Dzięki tej klasyfikacji możemy używać narzędzia, które pozwala nam zdecydować, które dane powinien skonfigurować użytkownik, a które powinny znaleźć się w tagu. Dane zbierane automatycznie można bezpiecznie odczytywać bezpośrednio ze zdarzenia. Wszystko inne powinno być skonfigurowane przez użytkownika.

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

• Identyfikator pomiaru: id: ponieważ nie jest on rejestrowany automatycznie, jest to jasny przykład wartości, którą użytkownik powinien wpisać podczas konfigurowania tagu.
• Nazwa zdarzenia: en: jak wspomnieliśmy powyżej, nazwa zdarzenia zawsze można pobrać bezpośrednio z parametru event_name. Ponieważ jednak jego wartość jest zdefiniowana przez użytkownika, warto zaoferować możliwość w razie potrzeby jej zastąpienia.
• URL strony, l: ta wartość może pochodzić z parametru page_location, który jest automatycznie zbierany przez tag przeglądarki Google Analytics 4 w przypadku każdego zdarzenia. Dlatego nie wymagaj od użytkownika wpisania wartości ręcznie.
• 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. Zamiast tego jest przechowywany w pliku cookie przeglądarki, aby umożliwić identyfikację użytkowników podczas wielu wizyt w witrynie. Jak widać w implementacji poniżej, do ustawiania pliku cookie jest używany tag serwera Baz Analytics, który używa interfejsu API setCookie. Oznacza to, że tylko tag Baza Analytics wie, gdzie i jak jest przechowywany plik cookie. Podobnie jak w przypadku l parametr u powinien być rejestrowany automatycznie.

Gdy zakończysz konfigurację tagu, powinna ona wyglądać mniej więcej tak:

Implementacja tagów

Teraz, gdy konfiguracja tagu została wyrównana, możesz przejść do implementowania jego działania w JavaScripcie w trybie piaskownicy.

Tag spełnia 4 działania:

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

Warto się też zastanowić, jak tag pasuje do całości kontenera. Różne komponenty kontenera odgrywają różne role. Są też możliwe działania, których tag nie może lub nie powinien.

• nie powinien sprawdzać zdarzenia w celu określenia, czy powinno zostać uruchomione. Do tego służy reguła.
• Nie należy uruchamiać kontenera z interfejsem API runContainer. To zadanie klienta.
• Z wyjątkiem plików cookie nie powinno się próbować wchodzić w bezpośrednią interakcję z żądaniem lub odpowiedzią. To również zadanie klienta.

Napisanie szablonu tagu, który spełnia wszystkie powyższe warunki, może wprowadzać w błąd użytkowników. Na przykład tag, który wysyła odpowiedź na żądanie przychodzące, uniemożliwi klientowi wykonanie tych samych działań. Spowoduje to niezgodność z oczekiwaniami użytkowników co do prawidłowego działania kontenera.

Mając to na uwadze, poniżej znajdziesz implementację tagu z adnotacjami w kodzie JS działającym w trybie piaskownicy.

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

Dzięki temu tag jest zaimplementowany. Aby korzystać z tagu, musisz odpowiednio skonfigurować jego uprawnienia w interfejsie API. W Edytorze szablonów otwórz kartę Uprawnienia i 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

Narysuj też testy tagu. Więcej informacji o testowaniu szablonów znajdziesz w sekcji testy w przewodniku dla programistów dotyczącym szablonów.

Na koniec pamiętaj, by co najmniej raz uruchomić tag za pomocą przycisku Uruchom kod. Dzięki temu unikniesz wielu prostych błędów, aby nie trafiły na Twój serwer.

Prześlij swój tag do Galerii szablonów społeczności

Wykonanie wszystkich czynności związanych z tworzeniem, testowaniem i wdrażaniem nowego tagu nie ma powodu, by robić to tylko dla siebie. Jeśli uważasz, że nowy tag może być przydatny dla innych osób, możesz przesłać go do Galerii szablonów społeczności.

Podsumowanie

W tym samouczku poznaliśmy podstawy pisania tagu na potrzeby kontenera serwera. Wiesz już:

• Interfejsy API, których chcesz używać do odczytywania danych zdarzeń, wysyłania żądań HTTP i ustawiania 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 jest to ważne.
• Rola tagu w kontenerze oraz informacje, co powinien, a czego nie.
• Kiedy i jak przesyłać szablony tagów do Galerii szablonów.