X Pixel + Web Conversions API — Documentazione

Traccia le conversioni X Ads da PrestaShop sia con eventi Pixel nel browser sia, opzionalmente, con eventi server-side tramite Web Conversions API.

Cosa traccia

• PageView tramite la configurazione di base di X Pixel.
• ViewContent nelle pagine prodotto.
• AddToCart tramite il bus eventi del carrello PrestaShop, con rilevamento fallback dei pulsanti per i temi più datati.
• AddToWishlist tramite i bus eventi wishlist più comuni e i gestori di clic.
• StartCheckout quando viene rilevata la pagina iniziale del checkout.
• Search quando il visitatore usa la pagina di ricerca PrestaShop.
• SignUp dopo la creazione di un account cliente.
• Purchase nella conferma d’ordine e nella validazione dell’ordine.
• Regole personalizzate per clic, URL, controller ed eventi DOM.

Compatibilità

Compatibile con PrestaShop da 1.6 a 9.0 (latest) e PHP 7.1+. Continuiamo a supportare anche le prossime versioni di PrestaShop.

Configurazione richiesta

1. Crea o apri la tua Event Source in X Ads Manager.
2. Copia la X Pixel ID nel modulo.
3. Abilita il tracciamento nel browser.
4. Aggiungi gli Event IDs per gli eventi di conversione che vuoi inviare. Purchase Event ID è obbligatorio quando il tracciamento degli acquisti è abilitato.
5. Salva le impostazioni e controlla il pannello di diagnostica.

La Pixel ID accetta lettere, numeri, underscore e trattini:

abc123_pixel-id

Il modulo usa questi hook PrestaShop:

displayHeader
displayOrderConfirmation
actionValidateOrder
actionCustomerAccountAdd

Impostazioni principali

Il modulo salva queste opzioni per il tracciamento e l’invio tramite 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

Gli Event IDs vengono configurati per ogni evento:

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

Gli Event IDs possono contenere lettere, numeri, underscore e trattini:

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

Consenso e traffico dei dipendenti

Quando Respect cookie consent è abilitato, il tracciamento attende il consenso marketing se mprcookiesrevolution o mprcookiebanner è attivo.

Il modulo legge questi segnali di consenso:

mprcr_consent=marketing:1
mprcookie_consent=granted

Se Exclude employees è abilitato, il modulo non inserisce il tracciamento mentre un dipendente collegato al back office naviga nel front office.

Web Conversions API

Abilita l’API solo dopo aver ottenuto le credenziali 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

Il modulo invia i payload di conversione in coda a X Ads API:

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

Gli eventi in coda vengono elaborati dal task cron del modulo:

send_x_conversions
schedule: every:300

Il limite batch della coda deve essere compreso tra 1 e 100. Il valore predefinito è:

CAPI_BATCH_LIMIT=20

Acquisizione di twclid

Lo script del browser acquisisce twclid dagli URL dei clic sugli annunci X e lo salva per abbinare gli eventi API:

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

Il nome del cookie salvato è:

mprxpix_twclid

Per il test API nell’amministrazione, usa un vero twclid proveniente da un clic su un annuncio X. Il campo di test accetta lettere, numeri, punti, underscore, due punti e trattini:

CAPI_TEST_TWCLID=abc.123_test-id

Regole eventi personalizzate

Gli eventi personalizzati vengono inseriti come JSON in Custom event rules. Ogni regola richiede un nome evento e x_event_id.

Esempio di regola per clic:

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

I trigger supportati sono:

click
url
controller
event

Esempio di regola URL:

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

Esempio di regola controller:

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

Esempio di regola evento DOM:

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

Per le regole di clic, il modulo legge anche parametri extra dagli attributi data 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>

Nomi degli eventi browser

Il modulo normalizza i nomi degli eventi comuni prima dell’invio:

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

Diagnostica

La pagina delle impostazioni include la diagnostica Web Conversions API:

• Contatori della coda per eventi in sospeso, in invio, inviati e non riusciti.
• Controlli di prontezza per Pixel ID, tracciamento browser, Purchase Event ID, credenziali OAuth, regole personalizzate, acquisizione twclid e tabella della coda.
• Righe degli eventi recenti con nome evento, stato, tentativi, codice HTTP, data di aggiornamento e ultimo errore.
• Send API probe per testare le credenziali con un vero twclid.
• Retry failed events per riportare gli eventi non riusciti nella coda in sospeso.

Checklist pratica di configurazione

1. Inserisci PIXEL_ID.
2. Abilita ENABLED.
3. Mantieni RESPECT_CONSENT abilitato se il tuo negozio usa il consenso ai cookie.
4. Mantieni EXCLUDE_EMPLOYEES abilitato mentre testi dal back office.
5. Aggiungi EVENT_ID_PURCHASE prima di abilitare il tracciamento degli acquisti.
6. Aggiungi gli altri Event IDs che vuoi usare per l’ottimizzazione di X Ads.
7. Abilita CAPI_ENABLED solo dopo aver aggiunto tutte e quattro le credenziali OAuth.
8. Usa il pannello di diagnostica per verificare la coda e il test API.