Wszystkie strony pomocy

Inna platforma i integracja dla programistów

Na platformie innej niż WooCommerce i Shoper wklejasz kod instalacyjny w sekcji <head> sklepu, a zdarzenia e-commerce przekazujesz przez dataLayer. Zakupy z serwera sklepu (zalecane) wysyła programista podpisanym żądaniem do TallyHost.

Kod instalacyjny

Snippet ładuje się tylko z własnej domeny sklepu (subdomena, np. rk4vqz.twojsklep.pl, „Ustawienia strony” → „Własna domena”; zobacz Szybki start, krok 2). Blokery reklam nie odróżnią jej od sklepu. Panel pokazuje kod instalacyjny dopiero wtedy, gdy domena jest aktywna; wcześniej pokazuje rekordy DNS i stan sprawdzenia.

Wklej kod w sekcji <head> każdej strony sklepu, przed innymi tagami marketingowymi:

<script async src="https://rk4vqz.twojsklep.pl/s.js"
  data-pk="pk_…"
  data-site="<identyfikator strony>"></script>

Dokładny kod dla twojej strony zawsze pokazuje panel: w kroku 2 konfiguracji i w ustawieniach strony. Skopiuj go z panelu, zamiast przepisywać.

  • data-pk — publiczny klucz strony.
  • data-site — identyfikator strony. Atrybut jest wymagany: bez niego zakup z przeglądarki bez event_id dostaje losowy identyfikator i nie połączy się z tym samym zakupem z serwera sklepu.

Kod z panelu nie ma atrybutu data-endpoint: snippet wysyła zdarzenia do domeny, z której się załadował, czyli do twojej własnej domeny.

Kod wklej tylko raz na stronę. Druga kopia snippetu na tej samej stronie się nie uruchomi.

Kod z adresem t.tallyhost.io wklejony przed wprowadzeniem obowiązkowej domeny zamień na kod z panelu po aktywacji domeny: adres TallyHost blokują listy filtrów, więc część zdarzeń z przeglądarki ginie. Gdy zmienisz domenę (nowa aktywna, stara usunięta), kod w panelu też się zmieni — podmień go w sklepie.

Atrybuty opcjonalne

  • data-cmp="tcf" — baner cookies sklepu działa na IAB TCF. Stub __tcfapi banera musi być w <head> przed s.js. Zobacz Baner cookies (CMP) i zgody.
  • data-meta-pixel="<pixel id>" — snippet załaduje Pixel Meta, ale dopiero po zgodzie klienta. Używaj tylko wtedy, gdy sklep nie ładuje Pixela w inny sposób. Zobacz Meta Pixel, Google Tag Manager i inne wtyczki.
  • data-ga="G-…" — identyfikator usługi GA4. Snippet odczyta z cookies GA4 identyfikator sesji, dzięki czemu zakup z serwera trafi do tej samej sesji co wizyta klienta.
  • data-test-event-code="<kod>" — kod zdarzeń testowych (do 64 znaków: litery, cyfry, _ i -). Zdarzenia z tym kodem trafiają do narzędzi testowych dostawców. Na co dzień tryb testowy ustawiasz w destynacji w panelu.
  • data-custom-events="1" — snippet wysyła zdarzenia własne z dataLayer (zobacz niżej). Panel dodaje ten atrybut do kodu instalacyjnego, gdy strona ma listę zdarzeń własnych.
  • data-ga="G-…" i data-ga-fallback="1" — uzupełnianie GA4, gdy tag Google jest zablokowany (opcja destynacji GA4; zobacz Meta Pixel, Google Tag Manager i inne wtyczki). Panel dodaje oba atrybuty do kodu instalacyjnego, gdy opcja jest włączona.
  • data-spa="1" — odsłona po każdej zmianie adresu strony bez przeładowania (aplikacje SPA).
  • data-layer-name="<nazwa>" — warstwa danych ma inną nazwę niż dataLayer (zobacz niżej „Inna nazwa dataLayer”).
  • data-ua-ecommerce="1" — sklep wysyła zdarzenia w starym formacie Universal Analytics (zobacz niżej). Panel dodaje ten atrybut, gdy włączysz „Stary format Enhanced Ecommerce” w ustawieniach strony.

Content Security Policy (CSP)

Jeśli sklep ma nagłówek Content Security Policy, dopisz do niego:

  • twoją własną domenę (np. https://rk4vqz.twojsklep.pl) w script-src i connect-src — z niej ładuje się s.js i do niej idą zdarzenia;
  • przy Pixelu Meta ładowanym przez snippet: https://connect.facebook.net w script-src i connect-src oraz https://www.facebook.com w connect-src i img-src (tam Pixel wysyła zdarzenia). Gdy Meta zmieni adresy Pixela, obowiązuje jej dokumentacja.

Zdarzenia e-commerce w dataLayer

Snippet sam wysyła wyświetlenie strony. Zdarzenia e-commerce odczytuje z window.dataLayer w formacie e-commerce GA4. Snippet wysyła je do dostawców:

  • view_item — wyświetlenie produktu,
  • add_to_cart — dodanie do koszyka,
  • begin_checkout — rozpoczęcie zamówienia,
  • add_payment_info — wybór płatności,
  • purchase — zakup.

Przykład wpisu:

window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "add_to_cart",
  event_id: crypto.randomUUID(),
  ecommerce: {
    currency: "EUR",
    value: 98.0,
    items: [
      { item_id: "SKU-1", item_name: "Kubek ceramiczny", price: 49.0, quantity: 2 }
    ]
  }
});

Zasady:

  • Pole event_id jest opcjonalne. Bez niego snippet nada zdarzeniu losowy UUID. Podaj własny event_id, jeśli Pixel w Google Tag Manager ma wysyłać to samo zdarzenie (zobacz Meta Pixel, Google Tag Manager i inne wtyczki). Dozwolony format to UUID albo 64 znaki hex małymi literami.
  • currency to kod waluty ISO 4217 (3 wielkie litery). Każda pozycja w items musi mieć item_id.
  • Zakup (purchase) musi mieć ecommerce.transaction_id, ecommerce.currency i ecommerce.value. Bez nich snippet go nie wyśle.
  • Snippet nie czyta danych klienta ze strony. Z dataLayer bierze tylko user_data.external_id (identyfikator klienta w sklepie), i to tylko przy zgodzie klienta.
  • Snippet czyta też wywołania gtag("event", …) (gtag zapisuje je w dataLayer). Pomija wywołania i wpisy wysyłane tylko do Google Ads (send_to z identyfikatorami AW-…, DC-… albo grupą GLA). To kopie zdarzeń GA4, które wtyczki dokładają dla reklam Google.
  • To samo zdarzenie wysłane dwa razy w ciągu 5 sekund (ten sam transaction_id albo te same produkty, warianty i ilości), na przykład przez dwie wtyczki naraz, snippet wysyła raz.
  • view_search_results snippet traktuje jak search, bez pola search_term.

Wtyczki i platformy, które odczytujemy

Sprawdziliśmy w kodzie (listopad 2026), co wysyłają do dataLayer popularne wtyczki i platformy. Snippet odczytuje bez dodatkowych ustawień:

  • WooCommerce: GTM4WP, Google Analytics for WooCommerce, Site Kit by Google, PixelYourSite (moduł GTM; moduł GA4 pisze do osobnej warstwy dataLayerPYS, ale wtyczka TallyHost dodaje wtedy własną), Pixel Manager for WooCommerce, Conversios, GTM for WooCommerce (Tag Pilot). Zobacz też Instalacja w WooCommerce.
  • Shoper: integracja Google Analytics 4 i Google Tag Manager (szablony Storefront i RWD). Zobacz Instalacja w Shoperze.
  • IdoSell, Sky-Shop: wbudowana integracja Google Analytics 4.
  • PrestaShop: oficjalny moduł Google Analytics (ps_googleanalytics) i Tag Concierge.
  • Magento 2 / Adobe Commerce: Magento_GoogleGtag, Yireo GoogleTagManager2, Magefan Google Tag Manager. Z włączonym starym formatem (niżej) także Adobe Commerce Google Tag Manager bez poprawki ACP2E-5176, Weltpixel i Mageplaza.

Wtyczki, które wysyłają zdarzenia tylko do Google Ads (Google for WooCommerce, PrestaShop Marketing with Google), nie dają nam zdarzeń: potrzebujesz jednej z wtyczek GA4 albo GTM z listy. Shopify nie używa dataLayer w koszyku i przy zamówieniu, więc kod instalacyjny tam nie wystarczy.

Inna nazwa dataLayer

Jeśli kontener Google Tag Manager ma inną nazwę warstwy danych (parametr l= w adresie gtm.js, np. gtmLayer), dodaj do kodu instalacyjnego data-layer-name="gtmLayer". Snippet czyta wtedy tę warstwę obok dataLayer: wywołania gtag() banera cookies i wtyczek trafiają do dataLayer bez względu na nazwę warstwy GTM. Nazwa to identyfikator JavaScript: litery, cyfry, _ i $, nie zaczyna się cyfrą. Wtyczka WooCommerce ustawia ją sama, gdy GTM4WP ma inną nazwę.

Stary format Universal Analytics

Moduły części sklepów (głównie Magento i PrestaShop) wciąż wysyłają zdarzenia w formacie Enhanced Ecommerce z Universal Analytics: ecommerce.detail, ecommerce.add, ecommerce.checkout, ecommerce.purchase.actionField. Włącz wtedy w panelu: Ustawienia strony → Ogólne → „Stary format Enhanced Ecommerce (Universal Analytics)” i podmień kod na stronie na ten z zakładki Instalacja. Snippet zamieni wtedy:

  • detail na view_item, add na add_to_cart, remove na remove_from_cart, impressions na view_item_list;
  • pierwszy krok checkout na begin_checkout (dalsze kroki pomija);
  • purchase na purchase: actionField.id to transaction_id, actionField.revenue to value, currencyCode to currency;
  • produkty: id na item_id, name na item_name, pierwszy człon category na item_category.

Gdy wpis ma oba formaty naraz, snippet bierze GA4. Format Universal Analytics ma zwykle revenue z podatkiem i dostawą. Jeśli zakupy idą też z serwera, wartość z serwera ma pierwszeństwo.

event_id zakupu

Zakup z przeglądarki i ten sam zakup z serwera muszą mieć ten sam event_id. Wtedy dostawcy go deduplikują, a TallyHost wysyła tylko zakup z serwera. event_id zakupu to hex sha256(site_id + ":" + order_id), gdzie order_id to wewnętrzny identyfikator zamówienia w sklepie.

Snippet liczy go sam z data-site i ecommerce.transaction_id. Jeśli transaction_id w dataLayer jest inny niż order_id używany na serwerze (na przykład to numer zamówienia widoczny dla klienta), dodaj do wpisu purchase gotowy event_id policzony z order_id.

Zdarzenia własne

Zdarzenia spoza listy e-commerce, np. select_plan albo trial_started, TallyHost wysyła do Meta i TikToka jako zdarzenia niestandardowe. Do GA4 idą tylko przy „Uzupełniaj GA4” (same nazwy), a do Google Ads jako konwersja, gdy w destynacji Google Ads przypiszesz zdarzeniu akcję konwersji (szczegóły).

  1. W panelu: Ustawienia strony → Ogólne → „Zdarzenia własne”. Wpisz nazwy zdarzeń, najwyżej 20. Nazwa zaczyna się literą, ma do 40 znaków: litery, cyfry i _. Wielkość liter ma znaczenie.
  2. Kod instalacyjny z zakładki Instalacja ma wtedy atrybut data-custom-events="1". Podmień kod na stronie raz. Późniejsze zmiany listy działają w ciągu kilku sekund, bez zmiany kodu. Gdy wyłączasz zdarzenia własne na stałe, usuń też atrybut.
  3. Wysyłaj zdarzenia jak do GA4: dataLayer.push({ event: "select_plan", plan: "pro" }) albo gtag("event", "select_plan", { plan: "pro" }).

Zasady:

  • Zdarzenia o nazwach spoza listy odrzucamy i nie liczymy ich do limitu planu.
  • Z parametrów wysyłamy najwyżej 10, tylko proste wartości: tekst do 100 znaków, liczby i true/false. Pomijamy parametry, których nazwa może wskazywać osobę albo adres strony (np. zawiera mail, phone, name, address, user, customer, city, url; także plan_name), oraz wartości wyglądające na adres URL, e-mail albo numer telefonu. Bez żadnej zgody klienta zdarzenie trafia do nas bez parametrów. Nie umieszczaj w parametrach danych osobowych.
  • Panel nie przyjmuje nazw zdarzeń standardowych Meta i TikToka (np. StartTrial, Lead, Checkout) ani zdarzeń automatycznych GA4 (np. scroll, form_submit): dostawcy pominęliby takie zdarzenia, a snippet ich nie wysyła.
  • Zdarzenia własne idą do Meta tylko z serwera (Conversions API). Pixel Meta ładowany przez snippet ich nie wysyła. Jeśli Pixel w Google Tag Manager wysyła to samo zdarzenie (trackCustom), dodaj do wpisu w dataLayer event_id i przekaż go Pixelowi jako eventID, inaczej Meta policzy zdarzenie dwa razy.
  • Zdarzenia własne liczą się do limitu zdarzeń planu jak inne.

Zakupy z serwera sklepu

Zakup wysłany z serwera sklepu liczy się także wtedy, gdy przeglądarka klienta blokuje skrypty, i niesie dane klienta do lepszego dopasowania. Na innej platformie jest zalecany, ale nie wymagany.

Klucz podpisu

Żądania z serwera podpisujesz kluczem Ed25519. Dziś klucz publiczny dla innych platform rejestruje zespół TallyHost: skontaktuj się z nami i podaj nazwę strony w panelu. W odpowiedzi dostaniesz identyfikator klucza (kid) do nagłówka podpisu. Klucz prywatny nigdy nie opuszcza twojego serwera.

Przykład wygenerowania pary kluczy w Node.js:

import { generateKeyPairSync } from "node:crypto";

const { publicKey, privateKey } = generateKeyPairSync("ed25519");
// Klucz publiczny do rejestracji: 32 bajty w base64url.
console.log(publicKey.export({ format: "jwk" }).x);
// Klucz prywatny zapisz w bezpiecznym miejscu na serwerze, nigdy w repozytorium.
const pem = privateKey.export({ format: "pem", type: "pkcs8" });

Żądanie

POST https://t.tallyhost.io/v1/collect z ciałem JSON i nagłówkami:

  • Content-Type: application/json
  • X-TH-Signature: t=<unix>,kid=<key_id>,ed25519=<base64url(podpis)>

Podpis Ed25519 obejmuje dokładnie t + "." + body, gdzie t to bieżący czas w sekundach unix, a body to bajty ciała żądania. Podpis nie obejmuje adresu URL, dlatego ciało musi zawierać pole pk. Czas t może różnić się od naszego zegara najwyżej o 300 sekund, więc zegar serwera musi być zsynchronizowany.

import { createHash, createPrivateKey, sign } from "node:crypto";

const privateKey = createPrivateKey(pem);
const eventId = createHash("sha256").update(`${siteId}:${orderId}`).digest("hex");

const body = JSON.stringify({ v: 1, pk, events: [/* zdarzenie zakupu */] });
const t = Math.floor(Date.now() / 1000);
const signature = sign(null, Buffer.from(`${t}.${body}`), privateKey).toString("base64url");

const res = await fetch("https://t.tallyhost.io/v1/collect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-TH-Signature": `t=${t},kid=${kid},ed25519=${signature}`
  },
  body
});

W PHP podpis da sodium_crypto_sign_detached($t . '.' . $body, $secretKey), zakodowany w base64url bez znaków =.

Ciało żądania

Przykład zakupu:

{
  "v": 1,
  "pk": "pk_…",
  "events": [
    {
      "event_id": "<sha256(site_id:order_id) w hex>",
      "event_name": "purchase",
      "event_time": "2026-11-04T10:21:14Z",
      "order_origin": "checkout",
      "page": { "url": "https://sklep.example/checkout/thank-you" },
      "user": {
        "em": "jan.kowalski@example.com",
        "ph": "+48600100200",
        "fn": "Jan",
        "ln": "Kowalski",
        "ct": "Wrocław",
        "zp": "50-001",
        "country": "PL",
        "external_id": "cust-12345",
        "client_ip_address": "203.0.113.24",
        "client_user_agent": "Mozilla/5.0 (…)",
        "fbp": "fb.1.1790690400123.1234567890",
        "ga_client_id": "1234567890.1790690400"
      },
      "consent": {
        "ad_storage": true,
        "ad_user_data": true,
        "ad_personalization": true,
        "analytics_storage": true,
        "source": "gcm"
      },
      "ecommerce": {
        "currency": "EUR",
        "value": 98.0,
        "transaction_id": "1001",
        "shipping": 5.0,
        "tax": 22.54,
        "items": [
          { "item_id": "SKU-1", "item_name": "Kubek ceramiczny", "price": 49.0, "quantity": 2 }
        ]
      }
    }
  ]
}

Pola żądania:

  • v — zawsze 1. pk — klucz publiczny strony. events — od 1 do 20 zdarzeń.
  • user i consent możesz podać także na poziomie żądania, jako wartości dla wszystkich zdarzeń. Pola z poziomu zdarzenia mają pierwszeństwo.

Pola zdarzenia zakupu:

  • event_id, event_name (purchase), event_time (czas RFC 3339, na przykład chwila opłacenia zamówienia) — wymagane.
  • ecommerce — wymagane transaction_id, currency i value; opcjonalnie shipping, tax, coupon i items (do 200 pozycji, każda z item_id; opcjonalnie product_id, item_name, price, quantity, item_category, item_brand, item_variant).
  • order_origin — skąd pochodzi zamówienie: checkout, store_api, admin, rest, renewal, pos albo other. Zamówienie złożone przez klienta w sklepie to checkout.
  • page.url — adres strony podziękowania, bez parametrów z danymi zamówienia.
  • user — dane klienta: em, ph, fn, ln, ct, st, zp, country, external_id. Możesz wysłać wartości surowe (znormalizujemy je i zahashujemy SHA-256 przed wysłaniem dalej) albo gotowe hashe SHA-256 (64 znaki hex). Do tego user_id (pseudonimowy identyfikator klienta, nie e-mail ani telefon), client_ip_address i client_user_agent zapisane przy złożeniu zamówienia oraz identyfikatory przeglądarki z cookies: fbp, fbc, ttp, ttclid, gclid, gbraid, wbraid, ga_client_id, ga_session_id.
  • consent — zgoda klienta (zobacz niżej).

Zwrot wysyłasz jako event_name: "refund" z ecommerce.refund_id (osobny dla każdego częściowego zwrotu) i event_id = hex sha256(site_id + ":" + order_id + ":refund:" + refund_id). Dziś zwroty trafiają tylko do Google Analytics 4.

Zgoda dla zakupu z serwera

Snippet zapisuje decyzję klienta z banera cookies w cookie __Host-th_consent (na stronach http: _th_consent). Wartość to obiekt consent w JSON, zakodowany jak w encodeURIComponent. Przy złożeniu zamówienia odczytaj to cookie, sprawdź, czy to poprawny obiekt (tylko znane pola: flagi logiczne, decided, source i vendors), i wyślij go z zakupem bez zmian. Brak cookie albo błędna wartość oznacza brak zgody: nie wysyłaj wtedy consent ani danych klienta. Taki zakup tylko liczymy.

Identyfikatory przeglądarki (fbp, ga_client_id i inne) zapisuj przy zamówieniu tylko wtedy, gdy pozwala na to zgoda. Wartości cookie nigdy nie pokazuj na stronie ani nie zapisuj w logach.

Kiedy wysyłać zakup

Wysyłaj zakup, gdy zamówienie zostanie opłacone, a nie w chwili jego utworzenia. Przy przelewie tradycyjnym albo płatności przy odbiorze te chwile mogą dzielić dni. Wysyłaj każdy zakup raz i nie blokuj nim składania zamówienia: wysyłka w tle, z kolejką i ponowieniami.

Odpowiedzi

  • 2xx — zakup przyjęty.
  • 409 — ten sam podpis został już przyjęty. Traktuj jak przyjęty.
  • 429 i 503 — ponów po czasie z nagłówka Retry-After.
  • Brak odpowiedzi, 502, 504 — ponów z rosnącym odstępem.
  • 401 — zły podpis, nieznany kid albo czas t poza oknem 300 sekund. Sprawdź zegar serwera i klucz.
  • 400 — błędne ciało. Odpowiedź podaje kod błędu. Nie ponawiaj tego samego żądania.
  • 403 — strona wstrzymana w TallyHost. 413 — ciało za duże (limit 64 KB).

Google Analytics 4 na innej platformie

Destynacja GA4 dostaje od TallyHost tylko zakupy, zwroty i leady z serwera sklepu. Pozostałe zdarzenia GA4 zbiera tag Google na stronie. Bez integracji z serwerem destynacja GA4 nie dostanie żadnych zdarzeń. Więcej: Meta Pixel, Google Tag Manager i inne wtyczki.

Jeśli potrzebujesz pomocy przy integracji, skontaktuj się z nami.