Alle Dokumentation

X Pixel + Web Conversions API — Dokumentation

Verfolgen Sie X Ads-Conversions in PrestaShop sowohl mit Browser-Pixel-Ereignissen als auch optional mit serverseitigen Web Conversions API-Ereignissen.

Was erfasst wird

  • PageView über die Basis-Konfiguration des X Pixels.
  • ViewContent auf Produktseiten.
  • AddToCart über den PrestaShop-Warenkorb-Event-Bus, mit Fallback-Erkennung von Buttons für ältere Themes.
  • AddToWishlist über gängige Wishlist-Event-Busse und Click-Handler.
  • StartCheckout, wenn die Startseite des checkouts erkannt wird.
  • Search, wenn der Besucher die PrestaShop-Suchseite nutzt.
  • SignUp nach der Erstellung eines Kundenkontos.
  • Purchase auf der Bestellbestätigungsseite und bei der Bestellvalidierung.
  • Benutzerdefinierte Regeln für Klicks, URLs, Controller und DOM-Events.
X Pixel + Web Conversions API — X pixel demo monitor X Pixel + Web Conversions API — Storefront order confirmation

Kompatibilität

Kompatibel mit PrestaShop 1.6 bis 9.0 (latest) und PHP 7.1+. Wir unterstützen auch kommende PrestaShop-Versionen weiterhin.

X Pixel + Web Conversions API — X pixel product events

Erforderliche Einrichtung

  1. Erstellen oder öffnen Sie Ihre Event Source im X Ads Manager.
  2. Kopieren Sie die X Pixel ID in das Modul.
  3. Aktivieren Sie das Browser-Tracking.
  4. Fügen Sie Event IDs für die Conversion-Events hinzu, die Sie senden möchten. Purchase Event ID ist erforderlich, wenn Purchase-Tracking aktiviert ist.
  5. Speichern Sie die Einstellungen und prüfen Sie das Diagnose-Panel.

Die Pixel ID akzeptiert Buchstaben, Zahlen, Unterstriche und Bindestriche:

abc123_pixel-id

Das Modul verwendet diese PrestaShop-Hooks:

displayHeader
displayOrderConfirmation
actionValidateOrder
actionCustomerAccountAdd
X Pixel + Web Conversions API — X pixel custom events

Haupteinstellungen

Das Modul speichert diese Optionen für Tracking und API-Übermittlung:

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 werden pro Ereignis konfiguriert:

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

Event IDs dürfen Buchstaben, Zahlen, Unterstriche und Bindestriche enthalten:

tw-viewcontent-123
tw-addtocart-123
tw-purchase-123
X Pixel + Web Conversions API — Admin x pixel diagnostics

Consent und Mitarbeiter-Traffic

Wenn Respect cookie consent aktiviert ist, wartet das Tracking auf Marketing-Consent, sofern mprcookiesrevolution oder mprcookiebanner aktiv ist.

Das Modul liest diese Consent-Signale:

mprcr_consent=marketing:1
mprcookie_consent=granted

Wenn Exclude employees aktiviert ist, bindet das Modul kein Tracking ein, während ein angemeldeter Back-Office-Mitarbeiter den Front Office-Bereich besucht.

X Pixel + Web Conversions API — Admin config custom events

Web Conversions API

Aktivieren Sie die API erst, nachdem Sie OAuth 1.0a Ads API-Zugangsdaten haben:

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

Das Modul sendet zwischengespeicherte Conversion-Payloads an die X Ads API:

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

Ereignisse in der Warteschlange werden durch die Cron-Aufgabe des Moduls verarbeitet:

send_x_conversions
schedule: every:300

Das Batch-Limit der Warteschlange muss zwischen 1 und 100 liegen. Der Standardwert ist:

CAPI_BATCH_LIMIT=20
X Pixel + Web Conversions API — Admin config event ids

twclid-Erfassung

Das Browser-Script erfasst twclid aus X-Anzeigenklick-URLs und speichert den Wert, um API-Ereignisse zuzuordnen:

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

Der gespeicherte Cookie-Name lautet:

mprxpix_twclid

Verwenden Sie für den Admin-API-Test eine echte twclid aus einem X-Anzeigenklick. Das Testfeld akzeptiert Buchstaben, Zahlen, Punkte, Unterstriche, Doppelpunkte und Bindestriche:

CAPI_TEST_TWCLID=abc.123_test-id
X Pixel + Web Conversions API — Admin config events

Benutzerdefinierte Ereignisregeln

Benutzerdefinierte Ereignisse werden als JSON in Custom event rules eingetragen. Jede Regel benötigt einen Ereignisnamen und x_event_id.

Beispiel für eine Klickregel:

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

Unterstützte Trigger sind:

click
url
controller
event

Beispiel für eine URL-Regel:

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

Beispiel für eine Controller-Regel:

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

Beispiel für eine DOM-Event-Regel:

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

Bei Klickregeln liest das Modul zusätzliche Parameter auch aus HTML-Datenattributen:

<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>
X Pixel + Web Conversions API — Admin config pixel

Browser-Ereignisnamen

Das Modul normalisiert gängige Ereignisnamen vor dem Versand:

ViewContent -> viewcontent
AddToCart -> addtocart
StartCheckout -> startcheckout
InitiateCheckout -> startcheckout
Purchase -> purchase
CompletePayment -> purchase
Search -> search
AddToWishlist -> addtowishlist
SignUp -> signup
CompleteRegistration -> signup
X Pixel + Web Conversions API — Admin config web capi

Diagnose

Die Einstellungsseite enthält Diagnosen für die Web Conversions API:

  • Warteschlangenzähler für ausstehende, sendende, gesendete und fehlgeschlagene Ereignisse.
  • Bereitschaftsprüfungen für Pixel ID, Browser-Tracking, Purchase Event ID, OAuth-Zugangsdaten, benutzerdefinierte Regeln, twclid-Erfassung und Warteschlangentabelle.
  • Aktuelle Ereigniszeilen mit Ereignisname, Status, Versuchen, HTTP-Code, Aktualisierungsdatum und letztem Fehler.
  • Send API probe zum Testen der Zugangsdaten mit einer echten twclid.
  • Retry failed events, um fehlgeschlagene Ereignisse wieder in die ausstehende Warteschlange zurückzusetzen.
X Pixel + Web Conversions API — Admin integrity

Praktische Setup-Checkliste

  1. Geben Sie PIXEL_ID ein.
  2. Aktivieren Sie ENABLED.
  3. Lassen Sie RESPECT_CONSENT aktiviert, wenn Ihr Shop Cookie-Consent verwendet.
  4. Lassen Sie EXCLUDE_EMPLOYEES aktiviert, während Sie aus dem Back Office testen.
  5. Fügen Sie EVENT_ID_PURCHASE hinzu, bevor Sie Purchase-Tracking aktivieren.
  6. Fügen Sie die weiteren Event IDs hinzu, die Sie für die Optimierung von X Ads verwenden möchten.
  7. Aktivieren Sie CAPI_ENABLED erst, nachdem Sie alle vier OAuth-Zugangsdaten eingetragen haben.
  8. Nutzen Sie das Diagnose-Panel, um die Warteschlange und den API-Test zu prüfen.
X Pixel + Web Conversions API — Admin readiness
Nach oben