Toda la documentación

X Pixel + Web Conversions API — Documentación

Realice el seguimiento de conversiones de X Ads desde PrestaShop con eventos Pixel en el navegador y, opcionalmente, con eventos del lado del servidor mediante Web Conversions API.

Qué se registra

  • PageView mediante la configuración base de X Pixel.
  • ViewContent en las páginas de producto.
  • AddToCart mediante el bus de eventos del carrito de PrestaShop, con detección alternativa de botones para temas antiguos.
  • AddToWishlist mediante buses de eventos de wishlist habituales y gestores de clics.
  • StartCheckout cuando se detecta la página de inicio del checkout.
  • Search cuando el visitante usa la página de búsqueda de PrestaShop.
  • SignUp después de la creación de una cuenta de cliente.
  • Purchase en la confirmación del pedido y en la validación del pedido.
  • Reglas personalizadas de clic, URL, controlador y evento DOM.
X Pixel + Web Conversions API — X pixel demo monitor X Pixel + Web Conversions API — Storefront order confirmation

Compatibilidad

Compatible con PrestaShop 1.6 a 9.0 (latest) y PHP 7.1+. Seguimos dando soporte a las próximas versiones de PrestaShop.

X Pixel + Web Conversions API — X pixel product events

Configuración necesaria

  1. Cree o abra su Event Source en X Ads Manager.
  2. Copie la X Pixel ID en el módulo.
  3. Active el seguimiento en el navegador.
  4. Añada Event IDs para los eventos de conversión que desea enviar. Purchase Event ID es obligatorio cuando el seguimiento de compras está activado.
  5. Guarde la configuración y revise el panel de diagnóstico.

La Pixel ID acepta letras, números, guiones bajos y guiones:

abc123_pixel-id

El módulo usa estos hooks de PrestaShop:

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

Ajustes principales

El módulo guarda estas opciones para el seguimiento y el envío por 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

Los Event IDs se configuran por evento:

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

Los Event IDs pueden contener letras, números, guiones bajos y guiones:

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

Consentimiento y tráfico de empleados

Cuando Respect cookie consent está activado, el seguimiento espera el consentimiento de marketing si mprcookiesrevolution o mprcookiebanner está activo.

El módulo lee estas señales de consentimiento:

mprcr_consent=marketing:1
mprcookie_consent=granted

Si Exclude employees está activado, el módulo no inyecta seguimiento mientras un empleado conectado al back office navega por el front office.

X Pixel + Web Conversions API — Admin config custom events

Web Conversions API

Active la API solo después de tener credenciales 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

El módulo envía los payloads de conversión en cola a X Ads API:

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

Los eventos en cola se procesan mediante la tarea cron del módulo:

send_x_conversions
schedule: every:300

El límite de lote de la cola debe estar entre 1 y 100. El valor predeterminado es:

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

Captura de twclid

El script del navegador captura twclid desde las URL de clic de anuncios X y lo guarda para asociar eventos API:

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

El nombre de la cookie guardada es:

mprxpix_twclid

Para la prueba API del administrador, use un twclid real procedente de un clic en un anuncio X. El campo de prueba acepta letras, números, puntos, guiones bajos, dos puntos y guiones:

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

Reglas de eventos personalizados

Los eventos personalizados se introducen como JSON en Custom event rules. Cada regla necesita un nombre de evento y x_event_id.

Ejemplo de regla de clic:

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

Los triggers compatibles son:

click
url
controller
event

Ejemplo de regla URL:

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

Ejemplo de regla de controlador:

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

Ejemplo de regla de evento DOM:

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

Para las reglas de clic, el módulo también lee parámetros adicionales desde atributos data de 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>
X Pixel + Web Conversions API — Admin config pixel

Nombres de eventos del navegador

El módulo normaliza los nombres de eventos comunes antes de enviarlos:

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

Diagnóstico

La página de ajustes incluye diagnósticos de Web Conversions API:

  • Contadores de cola para eventos pendientes, en envío, enviados y fallidos.
  • Comprobaciones de preparación para Pixel ID, seguimiento del navegador, Purchase Event ID, credenciales OAuth, reglas personalizadas, captura de twclid y tabla de cola.
  • Filas de eventos recientes con nombre del evento, estado, intentos, código HTTP, fecha de actualización y último error.
  • Send API probe para probar las credenciales con un twclid real.
  • Retry failed events para devolver los eventos fallidos a la cola pendiente.
X Pixel + Web Conversions API — Admin integrity

Lista práctica de configuración

  1. Introduzca PIXEL_ID.
  2. Active ENABLED.
  3. Mantenga RESPECT_CONSENT activado si su tienda usa consentimiento de cookies.
  4. Mantenga EXCLUDE_EMPLOYEES activado mientras prueba desde el back office.
  5. Añada EVENT_ID_PURCHASE antes de activar el seguimiento de compras.
  6. Añada los demás Event IDs que quiera usar para la optimización de X Ads.
  7. Active CAPI_ENABLED solo después de añadir las cuatro credenciales OAuth.
  8. Use el panel de diagnóstico para confirmar la cola y la prueba API.
X Pixel + Web Conversions API — Admin readiness
Volver arriba