X Pixel + Web Conversions API: konfiguracja i pomoc

1. Prześlij i zainstaluj ZIP w Moduły > "Module Manager", a następnie otwórz X Pixel + Web Conversions API > "Configure".
2. Wpisz Identyfikator X Pixel w Ustawienia X Pixel.
3. Wpisz rzeczywiste "ViewContent Event ID", Identyfikator zdarzenia zakupu i ID pozostałych konwersji, które chcesz włączyć.
4. Sprawdź przełączniki zdarzeń "Track", włącz "Enable X Pixel" i kliknij Zapisz.
5. Udziel zgody marketingowej w zwykłej przeglądarce odwiedzającego i otwórz stronę produktu.
6. Potwierdź załadowanie uwt.js i wysłanie skonfigurowanego zdarzenia ViewContent.
7. Jeśli używasz Web Conversions API, skonfiguruj wszystkie cztery dane dostępowe OAuth i zweryfikuj kwalifikujące się zdarzenie przez kolejkę i zadanie send_x_conversions.

• "Enable X Pixel". Główny przełącznik śledzenia X w przeglądarce; domyślnie: 0. Ustaw go na stronie konfiguracji modułu po wpisaniu prawidłowego "Pixel ID".

• Identyfikator X Pixel. ID źródła zdarzeń z "X Events Manager"; domyślnie: empty. Akceptuje litery, cyfry, podkreślenia i łączniki.

• "Exclude employees". Zatrzymuje wstawianie śledzenia, gdy zalogowany pracownik zaplecza przegląda sklep; domyślnie: 1.

• "Respect cookie consent". Czeka na zgodę marketingową, gdy działa mprcookiesrevolution lub mprcookiebanner; domyślnie: 1.

• "Track PageView". Pozwala podstawowemu wywołaniu konfiguracji X Pixel rejestrować odwiedziny; domyślnie: 1.

• "Track ViewContent". Wysyła zdarzenia wyświetlenia na stronach produktów, gdy skonfigurowano "ViewContent Event ID"; domyślnie: 1.

• "Track AddToCart". Wysyła zdarzenia dodania do koszyka na podstawie potwierdzonych udanych operacji dodania; domyślnie: 1.

• "Track StartCheckout". Wysyła zdarzenia rozpoczęcia zamówienia, gdy PrestaShop wykrywa stronę początku zamówienia, a koszyk zawiera produkty; domyślnie: 1.

• "Track Purchase". Wysyła zdarzenia zakupu przy potwierdzeniu i walidacji zamówienia; domyślnie: 1.

• "Track Search". Wysyła zdarzenia wyszukiwania w kontrolerze wyszukiwania PrestaShop, gdy istnieje zapytanie; domyślnie: 1.

• "Track AddToWishlist". Wysyła zdarzenia listy życzeń na podstawie potwierdzonych sygnałów powodzenia; domyślnie: 1.

• "Track SignUp". Wysyła zdarzenia rejestracji po utworzeniu konta klienta; domyślnie: 1.

• "ViewContent Event ID". ID zdarzenia X dla konwersji wyświetleń produktu; domyślnie: empty.

• "AddToCart Event ID". ID zdarzenia X dla konwersji dodania do koszyka; domyślnie: empty.

• "StartCheckout Event ID". ID zdarzenia X dla konwersji rozpoczęcia zamówienia; domyślnie: empty.

• Identyfikator zdarzenia zakupu. ID zdarzenia X dla konwersji zakupów; domyślnie: empty. Wymagane przy włączonym śledzeniu zakupów.

• "Search Event ID". ID zdarzenia X dla konwersji wyszukiwania; domyślnie: empty.

• "AddToWishlist Event ID". ID zdarzenia X dla konwersji listy życzeń; domyślnie: empty.

• "SignUp Event ID". ID zdarzenia X dla konwersji utworzenia konta; domyślnie: empty.

• "Track custom events". Włącza pole reguł JSON zdarzeń niestandardowych; domyślnie: 0.

• Reguły zdarzeń niestandardowych. Tablica JSON definiująca reguły konwersji kliknięć, URL, kontrolerów lub zdarzeń DOM; domyślnie: empty.

• "Enable Web Conversions API events". Kolejkuje kwalifikujące się zdarzenia serwerowe i wysyła je do X Ads API, gdy dane dostępowe są kompletne; domyślnie: 0.

• Klucz API X. Klucz konsumenta OAuth 1.0a dla X Ads API; domyślnie: empty.

• Sekret API X. Sekret konsumenta OAuth 1.0a dla X Ads API; domyślnie: empty.

• Token dostępu X. Token dostępu OAuth 1.0a dla X Ads API; domyślnie: empty.

• Sekret tokenu dostępu X. Sekret tokenu dostępu OAuth 1.0a dla X Ads API; domyślnie: empty.

• "Test twclid". Zachowane opcjonalne testowe ID kliknięcia; obecna próba odmawia wysłania; domyślnie: empty.

• "X Ads API version". Liczbowa wersja API używana w punkcie końcowym X Ads API; domyślnie: 12.

• "Send IP and user agent match keys". Zezwala na łączne użycie adresu IP i agenta użytkownika jako identyfikatorów dopasowania, gdy pozwala na to upoważnienie; domyślnie: 1.

• "Queue batch limit". Maksymalna liczba zdarzeń konwersji z kolejki przetwarzanych w jednym przebiegu, od 1 do 100; domyślnie: 20.

• "Persist consent withdrawals". Domyślnie: 0. Włącza trwałe weto po wycofaniu zgody marketingowej dla konwersji w kolejce.

Po zmianach kliknij Zapisz. Identyfikator X Pixel wymaga od 3 do 128 liter, cyfr, podkreśleń lub łączników. Dla każdej włączanej konwersji wpisz ID zdarzenia skonfigurowane na koncie. Pola ID zdarzeń są domyślnie puste. Określają definicję konwersji; są odrębne od conversion_id każdego wystąpienia używanego do deduplikacji.

Obecny formularz udostępnia też te ustawienia. Wszystkie przełączniki sygnałów mają domyślnie wartość Nie. Włącz tylko działania, które chcesz obserwować.

Wspólne progi to trzy wyświetlenia galerii, jedna zmiana wariantu, jedno kliknięcie szczegółów, 45 sekund przebywania i ograniczenie częstotliwości opcji do 1500 ms. Liczniki galerii, wariantów i szczegółów mają zakres od 1 do 20. Czas przebywania wynosi od 5 do 600 sekund. Ograniczenie częstotliwości wynosi od 250 do 60000 ms. Na przykład:

{"min_gallery_views":3,"min_variant_changes":1,"min_detail_clicks":1,"dwell_seconds":45,"option_throttle_ms":1500}

Możesz też podać gallery_selectors, variant_selectors i detail_selectors. Zachowaj wartości domyślne, chyba że motyw wymaga innych selektorów. Te opcjonalne sygnały wymagają kontroli zgody, zasad dotyczących pracowników i odpowiedzialności za śledzenie tak jak zdarzenia handlowe.

Podczas pierwszej konfiguracji pozostaw włączone ustawienia zgody i wykluczania pracowników. Testuj w zwykłej przeglądarce odwiedzającego bez oznaczenia pracownika. Zalogowana sesja zaplecza, reguła ruchu wewnętrznego lub rezygnacja odwiedzającego może blokować śledzenie.

Wspólna warstwa zgody obsługuje integracje zgody MPR i dodatkowe adaptery CMP. Musi uzyskać użyteczną decyzję marketingową dla miejsca docelowego. Nieznana, nieaktualna lub odmowna decyzja może wstrzymywać zdarzenia. Moduł nie dostarcza banera cookies. Starsze ustawienie zgody nie zastępuje bieżącej odmowy z wykrytej CMP.

Moduł musi odpowiadać za skonfigurowane miejsce docelowe we wspólnym koordynatorze śledzenia. Brak, niejednoznaczność lub konflikt odpowiedzialności może wstrzymać dostarczanie z przeglądarki i serwera. Usuń powielone tagi motywu lub ustal odpowiedzialny moduł, gdy inne rozszerzenie MPR zarządza tym samym kontem.

Wysyłanie produkcyjne podlega też zasadom ruchu wychodzącego. Zdarzenie widoczne w trybie demonstracyjnym lub podglądu nie musi trafić do konta reklamowego. Zakupy i serwerowe zdarzenia formularzy są wysyłane tylko ze zgodą, której kupujący udzielił w danym momencie; późniejsze uruchomienie cron nie może jej zastąpić.

Runtime ładuje https://static.ads-twitter.com/uwt.js i używa twq. Podstawowe PageView używa wywołania konfiguracji Pixela. Inne włączone zdarzenia wymagają przypisanych im ID zdarzeń X. Sam prawidłowy ID Pixela nie konfiguruje konwersji produktów, koszyka, rozpoczęcia zamówienia, zakupu, wyszukiwania, listy życzeń ani rejestracji.

Moduł używa hooków nagłówka i mediów do konfiguracji, potwierdzenia zamówienia do zakupu w przeglądarce, walidacji zamówienia do zapisania zgody kupującego i dodania kwalifikującej się wysyłki serwerowej do kolejki, a utworzenia konta do następnego kwalifikującego się zdarzenia rejestracji. Prywatne żądania wiążą dane zamówienia i rejestracji z natywną sesją odwiedzającego. Hooki stopki obsługują udane formularze kontaktowe. Oznaczenia pracowników są odświeżane przez hooki zaplecza i dispatchera.

StartCheckout wymaga wykrytej strony rozpoczęcia zamówienia i użytecznego kontekstu koszyka. Wyszukiwania wymagają dostępnego zapytania. Automatyczne zdarzenia koszyka wymagają udanej dodatniej zmiany ilości. Zdarzenia listy życzeń wymagają potwierdzonych udanych operacji dodania.

Prawidłowe kliknięcie reklamy twclid jest zapisywane jako mprxpix_twclid z czasem życia cookie 90 dni. X API może też używać innych upoważnionych identyfikatorów dopasowania, w tym IP i agenta użytkownika łącznie, jeśli włączone. ID kliknięcia nie jest jedynym możliwym serwerowym kluczem dopasowania.

Włącz "Track custom events", wklej tablicę JSON do Reguły zdarzeń niestandardowych i zapisz. Dostosuj selektory i ścieżki do sklepu. Używaj wyzwalaczy click, url, controller lub event. Reguła kontrolera może też zawierać listę modules. Nazwy zdarzeń dopuszczają litery, cyfry, podkreślenia i łączniki, do 64 znaków. Limit wynosi 15 różnych nazw. once ogranicza regułę w bieżącym czasie działania strony.

[
  {
    "event": "GalleryBrowse",
    "trigger": "click",
    "selector": ".product-images img,.images-container img",
    "params": {
      "property": "product_gallery"
    },
    "once": false,
    "x_event_id": "tw-replace-with-real-event-1",
    "capi": true
  },
  {
    "event": "LandingView",
    "trigger": "url",
    "contains": [
      "/special-offer"
    ],
    "params": {
      "property": "special_offer"
    },
    "once": true,
    "x_event_id": "tw-replace-with-real-event-2",
    "capi": true
  },
  {
    "event": "ContactView",
    "trigger": "controller",
    "controllers": [
      "contact"
    ],
    "params": {
      "property": "contact_page"
    },
    "once": true,
    "x_event_id": "tw-replace-with-real-event-3",
    "capi": true
  },
  {
    "event": "SizeGuideOpen",
    "trigger": "event",
    "dom_event": "mprxpix:custom",
    "params": {
      "property": "size_guide"
    },
    "once": false,
    "x_event_id": "tw-replace-with-real-event-4",
    "capi": true
  }
]

Wywołaj regułę DOM z motywu po inicjalizacji śledzenia:

document.dispatchEvent(new CustomEvent('mprxpix:custom'));

Zastąp każde przykładowe x_event_id rzeczywistym ID zdarzenia X. Runtime wysyła skonfigurowaną własną nazwę i cel. Reguły URL dopasowują ścieżkę strony, a nie parametry zapytania takie jak utm_campaign=x. Używaj skonfigurowanych parametrów reguły do obsługiwanych statycznych danych zdarzenia. Obecny handler wyzwalaczy nie scala dowolnych wartości DOM detail.params i data-x-param-*.

Typowe przychodzące nazwy zdarzeń są normalizowane do typów wewnętrznych. ViewContent mapuje się na view_item; AddToCart na add_to_cart; StartCheckout i InitiateCheckout na begin_checkout; Purchase i CompletePayment na purchase; Search na search; AddToWishlist na add_to_wishlist; SignUp i CompleteRegistration na sign_up.

Zadanie send_x_conversions jest zarejestrowane z harmonogramem every:300. Staje się wymagalne co pięć minut. Wspólny runner cron MPR musi wykonywać wymagalne zadania; sama deklaracja harmonogramu nie uruchamia procesu roboczego. Limit partii ogranicza wiersze kolejki przetwarzane w jednym przebiegu do 1-100, domyślnie 20.

Moduł nie udostępnia samodzielnego punktu wejścia cron.php. Użyj wspólnego harmonogramu już skonfigurowanego dla sklepu. Potwierdź w nim wykonanie zadań i sprawdź znaczniki czasu oraz stan kolejki na stronie konfiguracji modułu.

Diagnostyka obejmuje kontrole gotowości, liczniki kolejki, ostatnie wiersze, Wyślij próbę API i Ponów nieudane zdarzenia. Przed ponowieniem usuń przyczynę błędu. Przywrócenie nieudanych wierszy do oczekujących nie omija bieżących kontroli zgody, zasad pracowników, odpowiedzialności za konto ani miejsca docelowego.

Skonfiguruj wszystkie cztery dane dostępowe OAuth 1.0a dla Web Conversions API. Klient używa https://ads-api.x.com/{version}/measurement/conversions/{pixel_id} z liczbową "X Ads API version". Zainstalowana wartość to 12; zmieniaj ją tylko na wersję wymaganą przez konto i wdrożoną integrację API.

Widoczny przycisk Wyślij próbę API odmawia transmisji, ponieważ brak zweryfikowanego trybu testowego lub kodu zdarzenia testowego. Wypełnienie "Test twclid" nie umożliwia wysyłki testowej. Zamiast tego użyj autoryzowanego rzeczywistego zdarzenia i sprawdź wynik dostarczenia.

1. Sprawdź "Pixel ID", każde włączone ID zdarzenia, powiadomienia o wymaganej konfiguracji, gotowość, integralność i odpowiedzialność.
2. Udziel zgody marketingowej w zwykłej przeglądarce odwiedzającego.
3. Otwórz produkt i potwierdź uwt.js oraz zdarzenie dla swojego "ViewContent Event ID".
4. Wykonaj udane dodanie do koszyka i potwierdź przypisane zdarzenie koszyka.
5. Dla zamówienia testowego sprawdź conversion_id wystąpienia i wynik kolejki tam, gdzie włączono dostarczanie serwerowe.
6. Potwierdź wykonanie wspólnego zadania cron i sprawdź zapisy zdarzeń samej platformy.

Jeśli podstawowe śledzenie działa, a konwersje nie, sprawdź ID zdarzeń. Jeśli nic się nie ładuje, sprawdź stan pracownika i zgody, odpowiedzialność, zasady ruchu wychodzącego, powielone fragmenty twq lub SDK i blokady przeglądarki. Jeśli kolejka serwerowa zawodzi, sprawdź wszystkie cztery dane dostępowe, wersję API, dane dopasowania i uruchomienia harmonogramu. Pusta lub nieprawidłowa konfiguracja JSON zaangażowania może wstrzymać runtime do czasu poprawienia.

Obecny runtime nie udostępnia window.mprxpixTrack. W integracjach używaj skonfigurowanych reguł i obsługiwanych wyzwalaczy DOM.

Wyłącz przełączniki przeglądarki i serwera i zapisz, aby zatrzymać śledzenie z zachowaniem konfiguracji. Odinstaluj w "Module Manager", aby usunąć ustawienia modułu, wpisy menu i zarejestrowane zadania.

Odinstalowanie wywołuje wspólne czyszczenie kolejki konwersji. Wspólna tabela kolejki pozostaje, gdy używa jej inny moduł konwersji, i może zostać usunięta po usunięciu ostatniego użytkownika. Wyeksportuj potrzebną diagnostykę przed odinstalowaniem. Nie zakładaj, że odinstalowanie usuwa zdarzenia już wysłane do platformy reklamowej lub czyści cały magazyn atrybucji przeglądarki.

Wymaga PrestaShop 1.6 lub nowszego oraz PHP 7.1 lub nowszego.