Jak utworzyć tag serwera

W artykule Wprowadzenie do tagowania po stronie serwera znajdziesz omówienie tagowania po stronie serwera w Menedżerze tagów. Dowiesz się, czym są klienci i co robią: klienci otrzymują dane zdarzeń z urządzeń użytkowników i dostosowują je do użytku przez pozostałą część 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 w celu zebrania i analizy. Tagi mogą wysyłać dane w dowolne miejsce. Dopóki 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 konfiguracji niestandardowej:

• Google Analytics
• Żądanie HTTP

Jeśli chcesz wysyłać dane do innego miejsca niż Google Analytics lub potrzebujesz więcej funkcji niż te, które zapewnia tag żądania HTTP, musisz użyć innego tagu. Dodatkowe tagi znajdziesz w Galerii szablonów społeczności lub możesz napisać własne. Z tego samouczka dowiesz się, jak napisać własne tagi dla kontenera serwera.

Cele

• Dowiedz się, których interfejsów API używać do odczytywania danych zdarzeń, wysyłania żądań HTTP i ustawiania plików cookie w przeglądarce.
• Poznaj sprawdzone metody projektowania opcji konfiguracji tagu.
• Poznaj różnicę między danymi określonymi przez użytkownika a danymi zbieranymi automatycznie oraz dowiedz się, dlaczego to rozróżnienie jest ważne.
• Poznaj rolę tagu 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 ich podstawowych pojęć, takich jak klienci, tagi, reguły, i zmienne
• Znajomość podstaw tworzenia szablonów tagów i zmiennych

Tag Baz Analytics

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

Baz Analytics to prosta, hipotetyczna usługa analityczna, która pobiera dane za pomocą żądań HTTP GET wysyłanych na adres https://example.com/baz_analytics. Ma ona te parametry:

Konfiguracja tagu

Najpierw utwórz szablon tagu. W sekcji Szablony kontenera kliknij Nowy w sekcji Szablony tagów. Dodaj nazwę i opis tagu.

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

1. Pełna konfiguracja: dodaj pole konfiguracji dla każdego parametru. Wymagaj od użytkownika, aby wszystko ustawiał ręcznie.
2. Brak konfiguracji: nie dodawaj żadnych opcji konfiguracji tagu. Wszystkie dane są pobierane bezpośrednio ze zdarzenia.
3. Częściowa konfiguracja: dodaj pola dla niektórych parametrów, ale nie dla innych.

Pola dla każdego parametru zapewniają dużą elastyczność i dają użytkownikowi pełną kontrolę nad konfiguracją tagu. W praktyce jednak zwykle prowadzi to do powielania pracy. W szczególności takie elementy jak parametr l Baz Analytics, który zawiera adres URL strony, są jednoznaczne i uniwersalne. Wpisywanie tych samych, niezmiennych danych za każdym razem, gdy tag jest konfigurowany, najlepiej pozostawić komputerowi.

Może rozwiązaniem jest tag, który pobiera dane tylko ze zdarzenia. Jest to najprostszy tag do skonfigurowania przez użytkownika, ponieważ nie musi on nic robić. Z drugiej strony jest to też najbardziej restrykcyjna i podatna na błędy opcja. Użytkownicy nie mogą zmieniać działania tagu, nawet jeśli jest to konieczne. Na przykład mogą wywoływać zdarzenie purchase w swojej witrynie i w Google Analytics, ale Baz Analytics nazywa je buy. Albo założenia, które tag przyjmuje na temat struktury przychodzących danych zdarzeń, mogą nie odpowiadać rzeczywistości. W obu przypadkach użytkownik nie może nic zrobić.

Jak w wielu przypadkach, rozwiązanie leży gdzieś pomiędzy tymi dwoma skrajnościami. Niektóre dane zawsze warto pobierać ze zdarzenia. Inne dane powinny być konfigurowane przez użytkownika. Jak zdecydować, które dane powinny być konfigurowane przez użytkownika, a które powinny być określone w tagu? Aby odpowiedzieć na to pytanie, musimy przyjrzeć się bliżej danym przychodzącym do kontenera.

Skąd pochodzą dane?

Dane przychodzące do kontenera serwera z tagu Google Analytics można z grubsza 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 poleceniu event gtag.js. Na przykład polecenie takie jak to:

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

spowoduje utworzenie w kontenerze serwera tych parametrów:

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

Jest to dość proste, ale z perspektywy tagu bardzo trudne do pracy. Ponieważ te dane są wprowadzane przez użytkownika, mogą być dowolne. Być może, jak w powyższym przykładzie, użytkownik wysyła tylko zalecane zdarzenia i parametry, ale nie ma takiego obowiązku. 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 dane wprowadzane przez użytkownika to nie jedyne dane, które otrzyma kontener. Otrzyma on też wiele danych, które są automatycznie zbierane przez tag Google Analytics w przeglądarce. Są to m.in.:

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

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

Razem tworzą one dane zbierane automatycznie, o których wspomnieliśmy powyżej. Ogólnie rzecz biorąc, są to dane uniwersalne i semantycznie jednoznaczne. Gdy żądanie pochodzi z tagu Google Analytics w przeglądarce, te dane będą zawsze dostępne i zawsze będą miały ten sam format. Więcej informacji o tych parametrach znajdziesz w materiałach dotyczących zdarzeń.

Ta klasyfikacja daje nam przydatne narzędzie do decydowania, które dane powinny być konfigurowane przez użytkownika, a które powinny być określone w tagu. Dane zbierane automatycznie można bezpiecznie odczytywać bezpośrednio ze zdarzenia. Wszystko inne powinno być konfigurowane przez użytkownika.

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

• Identyfikator pomiaru, id: ponieważ nie jest zbierany automatycznie, jest to wyraźny przykład wartości, którą użytkownik powinien wpisać podczas konfigurowania tagu.
• Nazwa zdarzenia, en: jak wspomnieliśmy powyżej, nazwę zdarzenia można zawsze pobrać bezpośrednio z parametru event_name. Ponieważ jednak jego wartość jest definiowana przez użytkownika, warto dać mu możliwość zastąpienia nazwy w razie potrzeby.
• Adres URL strony, l: tę wartość można pobrać z page_location parametru, który jest automatycznie zbierany przez tag Google Analytics w przeglądarce przy każdym zdarzeniu. Dlatego nie należy wymagać od użytkownika ręcznego wpisywania wartości.
• Identyfikator użytkownika, u: w tagu serwera Baz Analytics parametr u nie jest ani określony przez użytkownika, ani zbierany automatycznie przez tag na stronie. Jest on przechowywany w pliku cookie przeglądarki, dzięki czemu użytkownicy mogą być identyfikowani podczas kolejnych wizyt w witrynie. Jak zobaczysz w implementacji poniżej, to tag serwera Baz Analytics używa interfejsu API setCookie do ustawiania pliku cookie. Oznacza to, że tylko tag Baz Analytics wie, gdzie i jak jest przechowywany plik cookie. Podobnie jak l, parametr u powinien być zbierany automatycznie.

Po skonfigurowaniu tagu powinien on wyglądać mniej więcej tak:

Implementacja tagów

Gdy konfiguracja tagu jest już gotowa, możesz przejść do implementowania jego działania w JavaScript w piaskownicy.

Tag musi wykonać 4 czynności:

1. Pobrać nazwę zdarzenia z konfiguracji tagu.
2. Pobrać adres URL strony z właściwości page_location zdarzenia.
3. Obliczyć identyfikator użytkownika. Tag będzie szukać identyfikatora użytkownika w pliku cookie o nazwie _bauid. Jeśli ten plik cookie nie jest obecny, tag obliczy nową wartość i zapisze ją na potrzeby przyszłych żądań.
4. Utworzyć adres URL i wysłać żądanie do serwera zbierania danych 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 są też rzeczy, których tag nie robi lub nie powinien robić. Twój tag:

• Nie powinien analizować zdarzenia, aby sprawdzić, czy ma się uruchomić. Do tego służy reguła.
• Nie powinien uruchamiać kontenera za pomocą interfejsu API runContainer. To zadanie klienta.
• Z ważnym wyjątkiem plików cookie nie powinien próbować bezpośrednio wchodzić w interakcję z żądaniem ani odpowiedzią. To też zadanie klienta.

Napisanie szablonu tagu, który wykonuje którąkolwiek z tych czynności, spowoduje, że użytkownicy Twojego tagu będą mieli problemy. Na przykład tag, który wysyła odpowiedź na przychodzące żądanie, uniemożliwi klientowi zrobienie tego samego. Spowoduje to, że użytkownicy nie będą wiedzieć, jak powinien działać kontener.

Mając to wszystko na uwadze, poniżej znajdziesz implementację tagu w JavaScript w piaskownicy z adnotacjami.

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 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 jest już zaimplementowany. Zanim zaczniesz używać tagu, musisz prawidłowo ustawić jego uprawnienia do interfejsu API. Otwórz kartę Uprawnienia w edytorze szablonów i określ te uprawnienia:

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

Warto też napisać testy dla tagu. Więcej informacji o testowaniu szablonów, znajdziesz w sekcji Testy w przewodniku dla deweloperów szablonów.

Na koniec nie zapomnij przynajmniej raz uruchomić tagu za pomocą przycisku Uruchom kod. Pozwoli to uniknąć wielu prostych błędów na serwerze.

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

Skoro już wykonałeś całą pracę związaną z tworzeniem, testowaniem i wdrażaniem nowego tagu, nie ma powodu, aby go nie udostępniać. Jeśli uważasz, że Twój nowy tag może być przydatny innym osobom, rozważ przesłanie go do Galerii szablonów społeczności.

Podsumowanie

Z tego samouczka dowiesz się, jak napisać tag dla kontenera serwera. Dowiesz się:

• których interfejsów API używać do odczytywania danych zdarzeń, wysyłania żądań HTTP i ustawiania plików cookie w przeglądarce;
• jakie są sprawdzone metody projektowania opcji konfiguracji tagu;
• jaka jest różnica między danymi określonymi przez użytkownika a danymi zbieranymi automatycznie oraz dlaczego to rozróżnienie jest ważne;
• jaka jest rola tagu w kontenerze oraz co tag powinien, a czego nie powinien robić;
• kiedy i jak przesyłać szablony tagów do Galerii szablonów społeczności.