X Pixel + Web Conversions API — Dokumentacja

Śledź konwersje X Ads w PrestaShop za pomocą zdarzeń Pixel w przeglądarce oraz opcjonalnych zdarzeń serwerowych Web Conversions API.

Co jest śledzone

• PageView przez podstawową konfigurację X Pixel.
• ViewContent na stronach produktów.
• AddToCart przez magistralę zdarzeń koszyka PrestaShop, z awaryjnym wykrywaniem przycisków dla starszych szablonów.
• AddToWishlist przez popularne magistrale zdarzeń wishlist i obsługę kliknięć.
• StartCheckout po wykryciu strony startowej checkout.
• Search, gdy odwiedzający korzysta ze strony wyszukiwania PrestaShop.
• SignUp po utworzeniu konta klienta.
• Purchase na stronie potwierdzenia zamówienia i podczas walidacji zamówienia.
• Niestandardowe reguły kliknięć, URL, kontrolerów i zdarzeń DOM.

Kompatybilność

Kompatybilny z PrestaShop 1.6 do 9.0 (latest) oraz PHP 7.1+. Nadal wspieramy kolejne wersje PrestaShop.

Wymagana konfiguracja

1. Utwórz lub otwórz swoją Event Source w X Ads Manager.
2. Skopiuj X Pixel ID do modułu.
3. Włącz śledzenie w przeglądarce.
4. Dodaj Event IDs dla zdarzeń konwersji, które chcesz wysyłać. Purchase Event ID jest wymagany, gdy włączone jest śledzenie zakupów.
5. Zapisz ustawienia i sprawdź panel diagnostyczny.

Pixel ID akceptuje litery, cyfry, podkreślenia i myślniki:

abc123_pixel-id

Moduł używa tych hooków PrestaShop:

displayHeader
displayOrderConfirmation
actionValidateOrder
actionCustomerAccountAdd

Główne ustawienia

Moduł zapisuje te opcje dla śledzenia i wysyłki API:

ENABLED=1
PIXEL_ID=your_x_pixel_id
EXCLUDE_EMPLOYEES=1
RESPECT_CONSENT=1

TRACK_PAGEVIEW=1
TRACK_VIEWCONTENT=1
TRACK_ADDTOCART=1
TRACK_STARTCHECKOUT=1
TRACK_PURCHASE=1
TRACK_SEARCH=1
TRACK_ADDTOWISHLIST=1
TRACK_SIGNUP=1
TRACK_CUSTOM_EVENTS=0

Event IDs są konfigurowane osobno dla każdego zdarzenia:

EVENT_ID_VIEWCONTENT=
EVENT_ID_ADDTOCART=
EVENT_ID_STARTCHECKOUT=
EVENT_ID_PURCHASE=
EVENT_ID_SEARCH=
EVENT_ID_ADDTOWISHLIST=
EVENT_ID_SIGNUP=

Event IDs mogą zawierać litery, cyfry, podkreślenia i myślniki:

tw-viewcontent-123
tw-addtocart-123
tw-purchase-123

Zgoda i ruch pracowników

Gdy Respect cookie consent jest włączone, śledzenie czeka na zgodę marketingową, jeśli aktywny jest mprcookiesrevolution lub mprcookiebanner.

Moduł odczytuje te sygnały zgody:

mprcr_consent=marketing:1
mprcookie_consent=granted

Jeśli Exclude employees jest włączone, moduł nie wstrzykuje śledzenia, gdy zalogowany pracownik back office przegląda front office.

Web Conversions API

Włącz API dopiero po uzyskaniu danych uwierzytelniających OAuth 1.0a Ads API:

CAPI_ENABLED=1
CAPI_CONSUMER_KEY=your_api_key
CAPI_CONSUMER_SECRET=your_api_secret
CAPI_ACCESS_TOKEN=your_access_token
CAPI_ACCESS_SECRET=your_access_token_secret
CAPI_API_VERSION=12
CAPI_SEND_IP_UA=1
CAPI_BATCH_LIMIT=20

Moduł wysyła zakolejkowane ładunki konwersji do X Ads API:

https://ads-api.x.com/12/measurement/conversions/{pixel_id}

Zdarzenia z kolejki są przetwarzane przez zadanie cron modułu:

send_x_conversions
schedule: every:300

Limit paczki kolejki musi mieścić się w zakresie od 1 do 100. Wartość domyślna to:

CAPI_BATCH_LIMIT=20

Przechwytywanie twclid

Skrypt w przeglądarce przechwytuje twclid z adresów URL kliknięć reklam X i zapisuje go do dopasowywania zdarzeń API:

https://www.example.com/product-name?twclid=abc123

Nazwa zapisanego pliku cookie to:

mprxpix_twclid

Do testu API w panelu administracyjnym użyj prawdziwego twclid z kliknięcia reklamy X. Pole testowe akceptuje litery, cyfry, kropki, podkreślenia, dwukropki i myślniki:

CAPI_TEST_TWCLID=abc.123_test-id

Niestandardowe reguły zdarzeń

Niestandardowe zdarzenia wpisuje się jako JSON w Custom event rules. Każda reguła wymaga nazwy zdarzenia oraz x_event_id.

Przykład reguły kliknięcia:

[
  {
    "event": "GalleryBrowse",
    "x_event_id": "tw-gallery-123",
    "trigger": "click",
    "selector": ".product-images img,.images-container img",
    "params": {
      "property": "product_gallery"
    },
    "capi": true
  }
]

Obsługiwane wyzwalacze to:

click
url
controller
event

Przykład reguły URL:

[
  {
    "event": "LandingPageVisit",
    "x_event_id": "tw-landing-123",
    "trigger": "url",
    "contains": ["/promo", "utm_campaign=x"],
    "params": {
      "property": "campaign_landing"
    },
    "once": true,
    "capi": true
  }
]

Przykład reguły kontrolera:

[
  {
    "event": "CheckoutPageView",
    "x_event_id": "tw-checkout-123",
    "trigger": "controller",
    "controllers": ["order"],
    "params": {
      "property": "checkout"
    },
    "capi": true
  }
]

Przykład reguły zdarzenia DOM:

[
  {
    "event": "ConfiguratorComplete",
    "x_event_id": "tw-configurator-123",
    "trigger": "event",
    "dom_event": "mprxpix:custom",
    "params": {
      "property": "configurator"
    },
    "capi": true
  }
]

Dla reguł kliknięć moduł odczytuje również dodatkowe parametry z atrybutów danych HTML:

<button
  class="track-x-demo"
  data-x-param-product_id="123"
  data-x-param-product_name="Demo product"
  data-mprxpix-param-property="custom_button">
  Track event
</button>

Nazwy zdarzeń przeglądarki

Moduł normalizuje popularne nazwy zdarzeń przed ich wysłaniem:

ViewContent -> viewcontent
AddToCart -> addtocart
StartCheckout -> startcheckout
InitiateCheckout -> startcheckout
Purchase -> purchase
CompletePayment -> purchase
Search -> search
AddToWishlist -> addtowishlist
SignUp -> signup
CompleteRegistration -> signup

Diagnostyka

Strona ustawień zawiera diagnostykę Web Conversions API:

• Liczniki kolejki dla zdarzeń oczekujących, wysyłanych, wysłanych i nieudanych.
• Kontrole gotowości dla Pixel ID, śledzenia w przeglądarce, Purchase Event ID, danych OAuth, niestandardowych reguł, przechwytywania twclid i tabeli kolejki.
• Ostatnie wiersze zdarzeń z nazwą zdarzenia, statusem, liczbą prób, kodem HTTP, datą aktualizacji i ostatnim błędem.
• Send API probe do testowania danych uwierzytelniających z prawdziwym twclid.
• Retry failed events, aby przywrócić nieudane zdarzenia do kolejki oczekujących.

Praktyczna lista kontrolna konfiguracji

1. Wpisz PIXEL_ID.
2. Włącz ENABLED.
3. Pozostaw RESPECT_CONSENT włączone, jeśli Twój sklep korzysta ze zgody na pliki cookie.
4. Pozostaw EXCLUDE_EMPLOYEES włączone podczas testowania z back office.
5. Dodaj EVENT_ID_PURCHASE przed włączeniem śledzenia zakupów.
6. Dodaj pozostałe Event IDs, których chcesz używać do optymalizacji X Ads.
7. Włącz CAPI_ENABLED dopiero po dodaniu wszystkich czterech danych OAuth.
8. Użyj panelu diagnostycznego, aby potwierdzić działanie kolejki i testu API.