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 bezevent_iddostaje 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__tcfapibanera musi być w<head>przeds.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 zdataLayer(zobacz niżej). Panel dodaje ten atrybut do kodu instalacyjnego, gdy strona ma listę zdarzeń własnych.data-ga="G-…"idata-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) wscript-srciconnect-src— z niej ładuje sięs.jsi do niej idą zdarzenia; - przy Pixelu Meta ładowanym przez snippet:
https://connect.facebook.netwscript-srciconnect-srcorazhttps://www.facebook.comwconnect-srciimg-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_idjest opcjonalne. Bez niego snippet nada zdarzeniu losowy UUID. Podaj własnyevent_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. currencyto kod waluty ISO 4217 (3 wielkie litery). Każda pozycja witemsmusi miećitem_id.- Zakup (
purchase) musi miećecommerce.transaction_id,ecommerce.currencyiecommerce.value. Bez nich snippet go nie wyśle. - Snippet nie czyta danych klienta ze strony. Z
dataLayerbierze tylkouser_data.external_id(identyfikator klienta w sklepie), i to tylko przy zgodzie klienta. - Snippet czyta też wywołania
gtag("event", …)(gtag zapisuje je wdataLayer). Pomija wywołania i wpisy wysyłane tylko do Google Ads (send_toz identyfikatoramiAW-…,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_idalbo te same produkty, warianty i ilości), na przykład przez dwie wtyczki naraz, snippet wysyła raz. view_search_resultssnippet traktuje jaksearch, bez polasearch_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:
detailnaview_item,addnaadd_to_cart,removenaremove_from_cart,impressionsnaview_item_list;- pierwszy krok
checkoutnabegin_checkout(dalsze kroki pomija); purchasenapurchase:actionField.idtotransaction_id,actionField.revenuetovalue,currencyCodetocurrency;- produkty:
idnaitem_id,namenaitem_name, pierwszy członcategorynaitem_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).
- 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. - 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. - Wysyłaj zdarzenia jak do GA4:
dataLayer.push({ event: "select_plan", plan: "pro" })albogtag("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. zawieramail,phone,name,address,user,customer,city,url; takżeplan_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 wdataLayerevent_idi przekaż go Pixelowi jakoeventID, 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/jsonX-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— zawsze1.pk— klucz publiczny strony.events— od 1 do 20 zdarzeń.usericonsentmoż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— wymaganetransaction_id,currencyivalue; opcjonalnieshipping,tax,couponiitems(do 200 pozycji, każda zitem_id; opcjonalnieproduct_id,item_name,price,quantity,item_category,item_brand,item_variant).order_origin— skąd pochodzi zamówienie:checkout,store_api,admin,rest,renewal,posalboother. Zamówienie złożone przez klienta w sklepie tocheckout.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 tegouser_id(pseudonimowy identyfikator klienta, nie e-mail ani telefon),client_ip_addressiclient_user_agentzapisane 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.429i503— ponów po czasie z nagłówkaRetry-After.- Brak odpowiedzi,
502,504— ponów z rosnącym odstępem. 401— zły podpis, nieznanykidalbo czastpoza 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.