Śledzenie e-commerce

Ten przewodnik opisuje, jak ręcznie zintegrować śledzenie e-commerce Trackboxx ze sklepem - niezależnie od tego, czy korzystasz z niestandardowego systemu, Shopify, Shopware, Magento czy innego sklepu. Dla WooCommerce dostępna jest oficjalna wtyczka, która automatycznie uruchamia wszystkie opisane tutaj zdarzenia.

Podstawowa logika: Co oznacza trackboxx('Purchase', [...])?

Zanim przejdziemy do poszczególnych zdarzeń, trzeba wyjaśnić jedną kwestię, która — jak pokazuje doświadczenie — jest najczęściej błędnie interpretowana:

Ważne: trackboxx('Purchase', [...]) nie jest pojedynczym zdarzeniem, lecz ogólnym wywołaniem dla wszystkich interakcji e-commerce. Pierwszy obiekt w tablicy określa śledzone zdarzenie za pomocą swojego pola type:

• { type: 'ViewProduct' } - Strona szczegółów produktu
• { type: 'AddToCart' } - Produkt dodany do koszyka
• { type: 'ViewCart' } - Wyświetl stronę koszyka zakupów
• { type: 'order' } - Zamówienie zrealizowane

Oznaczenie 'Purchase' w wywołaniu funkcji oznacza jedynie kategorię akcji „e-commerce” i pozostaje niezmienne, niezależnie od tego, czy śledzisz wyświetlenie produktu, dodanie go do koszyka czy faktyczny zakup.

Cztery zdarzenia e-commerce w skrócie

1. ViewProduct – Strona szczegółów produktu

Wyzwalacz: Podczas wywoływania strony szczegółów produktu.
Minimalne dane: Nazwa produktu i cena jednostkowa.

<script>
trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 99.90 }
]);
</script>Język kodu: HTML, XML (xml)

Uwagi:

• price = Cena jednostkowa produktu (wartość liczbowa z kropką jako separatorem dziesiętnym).
• Opcjonalne pola dodatkowe: sku, category.
• W przypadku wariantów lub pakietów przekaż pełną nazwę wariantu wraz z atrybutami (np. „T-shirt — czerwony, L”), aby dane w raportach były spójnie grupowane.

2. AddToCart – Produkt dodany do koszyka

Wyzwalanie: Po pomyślnym wykonaniu operacji „Dodaj do koszyka”, a nie po samym kliknięciu.
Minimalne dane: Nazwa produktu i cena jednostkowa.

<script>
trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 19.99 }
]);
</script>Język kodu: HTML, XML (xml)

Uwagi dotyczące czasu - w zależności od typu sklepu:

• Niestandardowe sklepy i koszyki AJAX: Wywołaj zdarzenie w funkcji zwrotnej uruchamianej po pomyślnym dodaniu produktu do koszyka, a nie w procedurze obsługi kliknięcia. Dzięki temu zdarzenie śledzenia nie zostanie zarejestrowane, jeśli produkt nie trafi do koszyka z powodu kontroli zapasów, błędu walidacji lub błędu sieci.
• Sklepy po stronie serwera z przekierowaniem: Wyzwól zdarzenie raz na następnej stronie po pomyślnym dodaniu.
• Prosta integracja za pomocą kliknięcia przycisku: dozwolone, ale tylko jeśli kliknięcie rzeczywiście prowadzi do pomyślnego dodania produktu, na przykład po sprawdzeniu, czy przycisk jest wyłączony dla wyprzedanych produktów.
• Deduplikacja: Wysyłaj AddToCart tylko raz na daną akcję, bez ponownego zliczania przy przeładowaniu strony lub powrocie do niej.

3. ViewCart – Strona koszyka

Wyzwalacz: Przy otwarciu strony koszyka.
Minimalne dane: Łączna kwota koszyka (amount). Opcjonalnie: wszystkie produkty w koszyku jako osobne obiekty.

<script>
trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Język kodu: HTML, XML (xml)

Uwagi:

• amount = całkowita kwota koszyka zakupów. Domyślnie: netto (odpowiada zachowaniu oficjalnej wtyczki WooCommerce).
• Jeśli Twój sklep stosuje ceny brutto, wartości brutto również są dozwolone. Kluczowa jest spójność w ramach jednego zdarzenia: cart.amount i wszystkie wartości product.price muszą być obliczane na tej samej podstawie, wszystkie netto albo wszystkie brutto.
• Do każdej pozycji w koszyku dodaj osobny obiekt product.
• Wartość price dla produktu odpowiada tutaj sumie danej pozycji (cena jednostkowa × ilość); zobacz sekcję „Logika ceny i ilość”.

4. Purchase – Zakończenie zamówienia (strona z podziękowaniem)

Wyzwalacz: Na stronie potwierdzenia zamówienia po pomyślnym dokonaniu płatności - dokładnie raz na zamówienie.
Minimalne dane: Identyfikator zamówienia, łączna kwota, wszystkie zakupione produkty.

<script>
trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Język kodu: HTML, XML (xml)

Opcjonalnie — z kuponem: Dla każdego wykorzystanego kuponu dodaj dodatkowy obiekt coupon.

<script>
trackboxx('Purchase', [
  { type: 'order', id: '12345', total: 149.70 },
  { type: 'coupon', name: 'SUMMER10', discount: 10.00 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Język kodu: HTML, XML (xml)

Uwagi:

• Zdarzenie Purchase nie ma poprzedzającego znacznika zdarzenia, takiego jak ViewProduct lub AddToCart — samo zdarzenie identyfikuje obiekt order.
• order.id = unikalny identyfikator zamówienia z systemu sklepu.
• order.total = całkowita wartość zamówienia (zalecana jest końcowa kwota brutto obejmująca wysyłkę i podatki, ale musi być zgodna z wartościami product.price).
• product.price = Suma pozycji (cena jednostkowa × ilość), a nie cena jednostkowa.
• Zapobiegaj wielokrotnemu wywołaniu zdarzenia przy przeładowaniu strony, na przykład za pomocą flagi po stronie serwera lub znacznika sesji.

Logika ceny i ilość

Trackboxx nie używa osobnego pola quantity. Ilości są uwzględniane pośrednio w cenie. Ta reguła jest wiążąca i należy ją stosować w ten sam sposób w każdej integracji:

Przykład: Trzy identyczne produkty w koszyku, po 19,99 € każdy, są wysyłane dla ViewCart i Purchase jako jeden obiekt product z price: 59.97, a nie jako trzy osobne obiekty i bez pola quantity.

Kolejność obiektów w tablicy

Aby zapewnić czystą i spójną integrację, zalecamy następującą sekwencję obiektów:

1. Znacznik zdarzenia lub obiekt order (ViewProduct / AddToCart / ViewCart / order)
2. Obiekt cart (tylko dla ViewCart)
3. Obiekty coupon (tylko dla Purchase, jeśli występują)
4. Obiekty product

Najlepsze praktyki

• Deduplikacja: Wysyłaj każde zdarzenie tylko raz na rzeczywistą akcję: unikaj podwójnego śledzenia przy przeładowaniu strony, powrocie do niej lub ponowieniu żądania AJAX.
• Moment wywołania: Wywołuj ViewProduct i ViewCart podczas ładowania strony, AddToCart po potwierdzonym dodaniu produktu do koszyka, a Purchase tylko raz na stronie z podziękowaniem.
• Ceny i kwoty: Przekazuj je jako Number, a nie ciąg znaków, z kropką jako separatorem dziesiętnym (np. 19.99, nie "19,99").
• Spójność: Wybierz dla sklepu wartości netto albo brutto i stosuj ten wybór konsekwentnie dla cart.amount, product.price i order.total.
• Ochrona danych: Nigdy nie przekazuj danych osobowych: adresów e-mail, imion i nazwisk, numerów klientów ani adresów. Respektuj udzieloną zgodę.

Szybka lista kontrolna dla systemu sklepowego

• WooCommerce: Użyj oficjalnej wtyczki Trackboxx. Uruchamia ona wszystkie cztery zdarzenia (ViewProduct, AddToCart, ViewCart, Purchase) automatycznie - bez konieczności ręcznej integracji.
• Custom Shops: Po stronie serwera wstaw nazwę produktu, cenę i sumę jako zmienne w odpowiednim skrypcie inline.
• Shopify: Wstaw fragmenty kodu do szablonów (product.liquid, cart.liquid, strona podziękowania po złożeniu zamówienia). W przypadku AddToCart użyj funkcji zwrotnej wywoływanej po pomyślnym zakończeniu żądania AJAX.
• Shopware / Magento: Podłącz wywołania do odpowiednich zdarzeń lub hooków w motywie albo wtyczce: strony produktu, strony koszyka, dodania produktu do koszyka i zakończenia zamówienia.

Odniesienie: Minimalne warianty

ViewProduct (minimalny)

trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Język kodu: JavaScript (javascript)

AddToCart (minimalny)

trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Język kodu: JavaScript (javascript)

ViewCart (minimalny)

trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 19.99 }
]);Język kodu: JavaScript (javascript)

Purchase (wariant minimalny)

trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 19.99 },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Język kodu: JavaScript (javascript)

Krótki przegląd: Najważniejsze zasady

• trackboxx('Purchase', [...]) jest ogólnym wywołaniem e-commerce, a nie zdarzeniem.
• Typ zdarzenia znajduje się w polu type pierwszego obiektu w przekazywanych danych (payload), a nie w wywołaniu funkcji.
• Wywołaj AddToCart po pomyślnym dodaniu produktu do koszyka, a nie po samym kliknięciu.
• cart.amount jest domyślnie wartością netto; wartości brutto są dozwolone, ale muszą być spójne w ramach zdarzenia.
• price oznacza cenę jednostkową dla ViewProduct i AddToCart oraz sumę pozycji dla ViewCart i Purchase.
• Nie ma osobnego pola quantity: ilości są uwzględniane w cenie.
• Zdarzenie Purchase opiera się na { type: 'order' }, bez poprzedzającego znacznika zdarzenia.
• Przekazuj ceny jako Number z kropką jako separatorem dziesiętnym, nigdy jako String.
• Nie przekazuj danych osobowych w payloadzie.