El pixel de ChatGPT Ads (oaiq): lo que el SDK acepta de verdad
La documentación de eventos de OpenAI dice qué eventos existen, pero no cómo se llaman desde el navegador. Si lo supones, el pixel parece bien puesto y no mide nada. Esto es lo que hay dentro del SDK, leído del fichero.
Por Marco Pilco Vinueza · actualizado el 14 de septiembre de 2026
Instalación: el script y el init
El script va en el <head>, lo más arriba posible (si carga tarde se pierden las conversiones tempranas). El pixelId es el identificador corto que enseña Ads Manager → Conversiones → Fuentes de datos, no el cds_… de la fuente.
<script>
(function(w,d,s,u){ if(w.oaiq) return; var q=function(){q.q.push(arguments)};
q.q=[]; w.oaiq=q; var js=d.createElement(s); js.async=true; js.src=u;
var f=d.getElementsByTagName(s)[0]; f.parentNode.insertBefore(js,f);
})(window,document,"script","https://bzrcdn.openai.com/sdk/oaiq.min.js");
oaiq("init", { pixelId: "<PIXEL-ID>" });
</script>
Con gestor de consentimiento: oaiq("consent", false) antes del init y oaiq("consent", true) cuando el usuario acepta. Por defecto arranca en true salvo denegación almacenada, y los eventos bloqueados no se reenvían después. Encaja con Consent Mode sin más trabajo.
La firma real: cuatro comandos y un shape
Leído del propio oaiq.min.js (v0.1.41, 7 de septiembre de 2026). Los únicos comandos que el dispatcher reconoce son init (alias initialize), consent, measure y measureSingle. No existe oaiq("event", …) ni oaiq("track", …): se ignoran en silencio.
oaiq("measure", "order_created", {
type: "contents", // el SHAPE, no el nombre del evento
amount: 4250, currency: "EUR", // 42,50 € en unidad menor entera
contents: [{ id: "sku-1", name: "Producto", quantity: 1, amount: 4250, currency: "EUR" }]
}, { event_id: "<id-del-pedido>" }); // misma clave que en la Conversions API
oaiq("measure", "lead_created", { type: "customer_action" }, { event_id: "<id-del-lead>" });
| Evento | Shape (data.type) | Campos admitidos en data |
|---|---|---|
| order_created · checkout_started · items_added · contents_viewed · page_viewed | contents | type, amount, currency, contents |
| lead_created · registration_completed · appointment_scheduled | customer_action | type, amount, currency |
| subscription_created · trial_started | plan_enrollment | type, plan_id, amount, currency, contents |
| custom | custom | type, plan_id, amount, currency, contents (no optimizable en oCPC) |
Lo que pasa si pones type: "order_created": el SDK descarta la conversión, emite un console.warn de "validation failed; event dropped" que nadie ve, y en su lugar envía un evento oai::diagnostic con missing_required_field: data.type. Ese diagnóstico también responde 202. Por eso el 202 del navegador no prueba nada.
options solo admite event_id, custom_event_name y opt_out. currency valida contra tres letras. Cookies propias: __oppref, __obref, __oaiq_consent.
Cómo verificar que llega (tres niveles)
- 1. pixel-config.
https://bzrcdn.openai.com/pixel-config/v1/<PIXEL-ID>.jsonresponde 200: el pixel existe y está reconocido. Es la comprobación más rápida de que el alta está bien Fuente: SDK v0.1.41, 07-09-2026 - 2. Modo debug.
oaiq("init", {pixelId, debug: true})saca en consola los avisos de validación que en producción se tragan Fuente: SDK v0.1.41, 07-09-2026 - 3. El sondeo del Ads Manager. Conversiones → Flujo de eventos → Iniciar sondeo enseña en vivo lo que llega, con su JSON. El equivalente al Test Events de Meta. Es la prueba buena: el
request-bodydel POST a/v1/sdk/eventstiene que llevar tu evento, nooai::diagnosticFuente: consola, 08-09-2026
Y una trampa de lectura: GET /conversions/event_settings devuelve lista vacía justo después de un alta correcta, y GET /conversions/events tarda en reflejar lo recién enviado. Verifica contra el sondeo, no contra el GET.
oppref: el identificador que une el clic con la conversión (y con GA4)
OpenAI añade a toda URL de destino un parámetro oppref (y olref). El pixel lo captura en una cookie propia y es lo que empareja el clic con la conversión. Dos consecuencias prácticas:
Tiene que sobrevivir a tus redirects. Un salto de http a https, de sin www a con www, o un test A/B que reescriba la URL sin conservar la query, lo pierde. El checker de la página principal lo comprueba siguiendo la cadena con un valor de prueba.
Es la forma fiable de ver este tráfico en GA4. Las UTM a nivel de campaña se pierden en buena parte de las sesiones (consentimiento, redirecciones) y el tráfico aterriza como directo. Filtrar por landing page que contenga oppref captura las sesiones reales del canal, con consentimiento o sin él.
Para la Conversions API (POST https://bzr.openai.com/v1/events?pid=<PIXEL-ID>), el oppref no se captura solo: hay que arrastrarlo desde la landing hasta el servidor y enviarlo en el evento, con el mismo id que el event_id del pixel para deduplicar. Gana el primero que llega.
Preguntas frecuentes
¿Cómo sé que el pixel de ChatGPT Ads está bien instalado?
Tres niveles, en orden. Uno: la configuración del pixel se descarga de bzrcdn.openai.com/pixel-config/v1/
¿Por qué oaiq("event", ...) no mide nada?
Porque ese comando no existe. El SDK (versión 0.1.41, leída el 7 de septiembre de 2026) solo reconoce init, consent, measure y measureSingle. Cualquier otro nombre se ignora en silencio: sin error en consola, sin petición de red.
¿Qué es data.type?
El shape del evento, no su nombre. order_created, checkout_started, items_added, contents_viewed y page_viewed usan el shape contents; lead_created, registration_completed y appointment_scheduled usan customer_action; subscription_created y trial_started usan plan_enrollment. Si pones el nombre del evento en type, el SDK descarta la conversión, envía un evento de diagnóstico y el navegador ve un 202 igual.
¿Cómo se envía el importe?
En amount, no en value, y en unidad menor entera: 42,50 € son 4250, con currency en ISO 4217 (EUR).
¿Qué es oppref y por qué importa?
El identificador de clic que OpenAI añade a la URL de destino (?oppref=...). El pixel lo guarda en una cookie propia y es lo que empareja clic y conversión. Si un redirect lo descarta, se pierde el emparejamiento. La Conversions API no lo captura sola: hay que arrastrarlo desde la landing y enviarlo.
¿Pixel o Conversions API?
Las dos, con el mismo id de evento para deduplicar. La propia documentación dice que la Conversions API es una fuente más fiable que el pixel solo. Los eventos de app (app_installed, app_opened) solo van por la API.
Si te han salido rojos, te los miro yo
Déjame tu correo y el dominio. Te escribo en menos de 24 horas con qué está bloqueando la aprobación, qué hay que pedir a IT y si el canal tiene sentido para tu negocio con los números que tienes.