X Ads, twq Universal Tag y Conversions API

Tracking de conversiones server-side para X Ads (anteriormente Twitter Ads). Pixel-ID emparejado con una Conversions API key. Modo híbrido opcional carga el twq Universal Website Tag de navegador, deduplicado vía conversion_id.

Requisitos

• Cuenta de X Ads Manager con rol Account Administrator o Ad Manager.
• Fuente de eventos Web Conversion existente (el equivalente a un Pixel en X) asociada a tu dominio.
• Aproximadamente 5 minutos.

1. Localizar el X Pixel-ID

• Abre X Ads Manager en ads.x.com.
• Tools → Conversion Tracking → Web.
• Selecciona la fuente de eventos para este dominio. Si no existe ninguna, créala en Add new event source → Web.
• El Pixel-ID (alfanumérico, ~5 a 6 caracteres, formato como ojxyz) aparece en el header de la fuente. Cópialo.

2. Generar una Conversions API key

• En la misma página de la fuente de eventos: Conversion API → Generate API key.
• X emite un bearer token de larga duración, scoped a la fuente de eventos. En operación normal no caduca, pero puede revocarse manualmente.
• La key se muestra UNA vez. Cópiala inmediatamente. No hay mecanismo de recuperación posterior, tendrías que revocar y regenerar.

3. Pegar credenciales en Beaconry

WordPress Admin → Beaconry → Tracking → X Ads. Pega Pixel-ID y API key, guarda.

La key se guarda cifrada en reposo con AES-256-GCM (ligada a los auth salts de WordPress). Alternativa con constantes: BCNR_X_ADS_PIXEL_ID y BCNR_X_ADS_API_KEY en wp-config.php.

4. Enviar el evento de prueba

Pulsa Enviar evento de prueba de X Ads. Beaconry dispara una conversión de prueba síncrona a través del primer slot configurado (prioridad: purchase, lead, signup, addtocart, pageview) y reporta la respuesta inline.

HTTP 200 sin errores significa que las credenciales funcionan. El evento aparece en Tools → Conversion Tracking → Health en aproximadamente 30 minutos. X Ads no tiene una vista de prueba en tiempo real comparable a Test Events de Meta, la pestaña Health es la que tienes que mirar.

Sobre el click identifier

X añade ?twclid=... (el X Click ID) a cada landing URL de clic-de-anuncio. Beaconry lo captura en la primera carga y lo persiste en la cookie nl_ext junto a fbclid, gclid, ttclid, msclkid y sc_at. Los eventos server-side llevan entonces twclid para una atribución limpia. Sin él, X cae a matching por PII hasheado más IP y User-Agent.

Modo híbrido, twq Universal Tag

CAPI server-side por sí sola cubre el 100 por ciento de los visitantes con consentimiento. El modo híbrido carga el twq Universal Website Tag de navegador (static.ads-twitter.com/uwt.js) en paralelo para que X vea las cookies first-party del visitante. Beaconry envía el mismo conversion_id desde ambos lados como tercer argumento a twq('event', ..., {conversion_id: ...}), X deduplica para evitar doble conteo.

Activar en Beaconry → Tracking → X Ads → Modo híbrido. Mejor match-rate, algo más de bytes para el visitante. Apagado por defecto.

Qué se envía automáticamente

X Ads no usa nombres de evento vendor como Meta o TikTok. Cada evento de conversión está ligado a un event_id base-36 por evento que tú creas en X Events Manager. Beaconry mapea los eventos canónicos GA4 a cinco slots; en cada slot pegas el event_id de X correspondiente bajo Beaconry → Tracking → X Ads:

Los eventos sin event_id de slot configurado se omiten silenciosamente: solo los slots que defines en la pestaña Tracking se envían realmente. Todos los payloads llevan PII hasheado (em, ph) cuando esté disponible, el twclid capturado, más IP y User-Agent.

Gestión de reembolsos: los reembolsos no se envían aquí. Van solo a GA4, ya que ningún canal publicitario tiene un evento de reembolso real.

Troubleshooting

• "401 invalid_credentials": API key revocada o generada bajo otra fuente de eventos. Regenera en la página de la fuente y reemplaza en Beaconry.
• "400 invalid_event_name": se envió un nombre de evento personalizado que no está en el vocabulario estándar de X. Beaconry solo envía nombres estándar de la tabla anterior. Los eventos NLData.track() personalizados con nombres no estándar se descartan en el canal de X.
• La pestaña Health muestra cero eventos recibidos: el tráfico HTTP saliente desde tu origen hacia ads-api.x.com puede estar bloqueado. Revisa las reglas WAF o de firewall del hosting. La pestaña Logs de Beaconry muestra el error HTTP completo.
• El contador se dispara tras activar el modo híbrido: el tercer argumento de twq('event', ...) debe ser {conversion_id: ...}, no {eventID: ...}. X usa un nombre de campo distinto al de Meta. El loader híbrido de Beaconry pone el correcto automáticamente, pero verifica que no tienes un snippet twq personalizado paralelo con el campo equivocado.