Tutorial: Z zagnieżdżonego dataLayer zbudować trwałe zmienne GTM

Zmienna warstwy danych w Google Tag Managerze (GTM) może zwracać liczbę, tekst, obiekt lub całą tablicę. Notacja kropkowa wybiera wartość z zagnieżdżonych danych. Najważniejsza jest różnica między nazwą pola a pozycją w tablicy: items.0 oznacza pierwszą pozycję, a nie konkretny produkt.

Trwałe zmienne wymagają udokumentowanej struktury, kompletnych danych zdarzenia i kontroli brakujących wartości. Indeks nadaje się do wskazania określonej pozycji; tożsamość produktu wymaga identyfikatora.

Kompletne zdarzenie add_to_cart

Przykład dodaje dwa krzesła i jeden stół w jednej operacji. Zdarzenie zawiera te nowo dodane produkty, a nie całą dotychczasową zawartość koszyka. Wartość wynosi 64.95 × 2 + 219.00 × 1 = 348.90, bez dostawy i podatku. Przy podaniu wartości wymagana jest waluta.

window.dataLayer = window.dataLayer || [];
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: "add_to_cart",
  ecommerce: {
    currency: "EUR",
    value: 348.90,
    items: [
      { item_id: "SKU-42", item_name: "Krzeslo", price: 64.95, quantity: 2,
        item_category: "Meble", index: 0 },
      { item_id: "SKU-77", item_name: "Stol", price: 219.00, quantity: 1,
        item_category: "Meble", index: 1 }
    ]
  },
  user: { logged_in: true, segment: "b2b" }
});

Inicjalizacja zachowuje istniejącą kolejkę. Wyczyszczenie ecommerce zapobiega przeniesieniu starych pól do tego kompletnego zestawu danych. Nazwa zdarzenia i związane dane należą do tego samego wywołania push. user.segment pokazuje dodatkowy stan aplikacji; samo przesłanie wartości nie konfiguruje właściwości użytkownika w GA4.

Odczyt zagnieżdżonych pól w wersji 2

Zmienna warstwy danych o nazwie wyświetlanej DLV - ecommerce.currency, ścieżce ecommerce.currency i wersji 2 zwraca EUR. Nazwa wyświetlana jest dowolna; wartość zależy od skonfigurowanej ścieżki. Kolejne zmienne mogą odczytywać ecommerce.value, ecommerce.items i ecommerce. Dwie ostatnie zwracają odpowiednio tablicę i obiekt.

Wersja 1 traktuje kropki jako dosłowne znaki w nazwie klucza. Wersja 2 interpretuje kropki jako zagnieżdżenie i potrafi także rozwinąć klucze takie jak {"page.type":"pdp"} do struktury zagnieżdżonej. Klucz z kropką nie wymaga więc automatycznie wersji 1. Jednolite obiekty zagnieżdżone pozwalają uniknąć niejednoznacznego mieszania kluczy z kropkami i właściwości obiektów.

Wielkość liter ma znaczenie. Brakująca ścieżka bez skonfigurowanej wartości domyślnej zwraca undefined. Dalsze zachowanie zależy od tagu i sposobu przekształcania wartości w wysyłane żądanie: parametr może zostać pominięty lub przekształcony, a własny kod może zakończyć się błędem. Brak wartości nie oznacza automatycznie pustego parametru ani konkretnej różnicy w raporcie.

Pozycja a tożsamość produktu

Nazwana ścieżka pozostaje użyteczna przy zgodnym schemacie i obecnych danych zdarzenia. Ścieżka z indeksem jest poprawna, gdy wymaganie brzmi „pierwszy produkt”; zmiana kolejności zmienia produkt na tej pozycji. Wyszukiwanie konkretnego produktu powinno używać item_id. Dla e-commerce GA4 odpowiednia jest zwykle cała tablica ecommerce.items. Własne przekształcenie nie jest potrzebne, jeśli źródło już dostarcza oczekiwany format.

Kolejka komunikatów i scalony model

window.dataLayer jest tablicą oczekujących komunikatów. GTM przetwarza komunikaty i utrzymuje wewnętrzny model danych. Wersja 2 może scalać obiekty i tablice także na kolejnych zagnieżdżonych poziomach: pominięte pola lub końcowe pozycje mogą pozostać z wcześniejszych komunikatów. Krótsza tablica nie usuwa więc niezawodnie poprzednich pozycji.

Przykłady Google dla e-commerce w GTM czyszczą poprzedni obiekt przez dataLayer.push({ecommerce:null}) przed wysłaniem kompletnego zdarzenia. Ten wzorzec pasuje do powyższego przykładu. Integracje celowo budujące stan przez kilka komunikatów wymagają uzgodnionego resetowania i kompletnych danych; bezrefleksyjne czyszczenie przed niepełnym zestawem może usunąć potrzebne wartości.

Opcjonalna walidacja bez wymyślonych wartości domyślnych

Poniższa niestandardowa zmienna JavaScript o nazwie JS - ecommerce valid odczytuje zmienną warstwy danych w wersji 2 o nazwie DLV - ecommerce. Funkcja zwraca wartość logiczną i nie zmienia źródła.

Przykładowe wymagania są celowo ścisłe: EUR, liczbowe nieujemne ceny i wartości, dodatnie całkowite ilości oraz niepusty tekst w co najmniej jednym polu item_id lub item_name. Każdy przekazany identyfikator i każda przekazana nazwa muszą być niepustym tekstem. GA4 akceptuje również produkt z samą nazwą; identyfikator nie jest bezwzględnie wymagany. Przy pominięciu ilości GA4 przyjmuje 1, lecz ten przykład wymaga jawnej ilości, aby ujawnić brakujące dane sklepu.

function () {
  var e = {{DLV - ecommerce}};
  function number(x) { return typeof x === "number" && isFinite(x); }
  function text(x) { return typeof x === "string" && x.trim() !== ""; }
  if (!e || e.currency !== "EUR" || !number(e.value) || e.value < 0 ||
      !Array.isArray(e.items) || !e.items.length) { return false; }
  var sum = 0;
  for (var i = 0; i < e.items.length; i++) {
    var a = e.items[i];
    if (!a || typeof a !== "object" || Array.isArray(a)) { return false; }
    if (!text(a.item_id) && !text(a.item_name)) { return false; }
    if (a.item_id !== undefined && !text(a.item_id)) { return false; }
    if (a.item_name !== undefined && !text(a.item_name)) { return false; }
    if (!number(a.price) || a.price < 0 ||
        !number(a.quantity) || a.quantity <= 0 ||
        Math.floor(a.quantity) !== a.quantity) { return false; }
    sum += a.price * a.quantity;
  }
  return isFinite(sum) && Math.abs(sum - e.value) < 0.005;
}

Porównanie dopuszcza różnicę zmiennoprzecinkową mniejszą niż pół eurocenta. To przykładowa kontrola dla EUR, a nie uniwersalny model walut, rabatów lub podatków. Bezpłatne produkty z rzeczywistą liczbową ceną 0 pozostają poprawne. Tekst taki jak "64.95", błędne ceny i zerowe ilości nie przechodzą kontroli zamiast po cichu zmieniać się w 0 lub 1. Opcjonalne pola produktów pozostają dostępne, ponieważ tablica nie jest przebudowywana.

Dla tagu GA4 add_to_cart reguła typu „Zdarzenie niestandardowe” używa nazwy add_to_cart i dodatkowego warunku {{JS - ecommerce valid}} równa się true. Parametry zdarzenia currency, value i items korzystają z odpowiednich zmiennych wersji 2. Kontrola musi być przypisana do tagu faktycznie wysyłającego dane; samo zwrócenie undefined przez inną zmienną nie zatrzymuje tagu. Inne reguły nie mogą omijać kontroli.

Sprawdzenie wybranego zdarzenia

W podglądzie GTM trzy widoki tego samego wybranego zdarzenia dostarczają uzupełniających informacji: oryginalny komunikat, wynikowy stan warstwy danych i obliczone zmienne. Dodatkowe pola modelu mogą być zamierzonym trwałym stanem, a nie błędem. Brak wyniku może wynikać z czasu odczytu, resetu, niewłaściwej wersji, pisowni lub własnej walidacji.

Przydatna sekwencja testowa obejmuje dwa produkty, jeden produkt, zmianę kolejności, produkt bezpłatny, produkt z samą nazwą oraz błędne dane. Po drugim, krótszym zdarzeniu nie mogą pozostawać stare produkty. Tag powinien uruchomić się raz dla poprawnych danych i pozostać zablokowany dla błędnych. Tag Assistant i wychodzące żądanie GA4 pozwalają następnie sprawdzić mapowanie; sam test funkcji nie sprawdza kontenera.