Código abierto

Un solo event_id para el navegador y tu servidor

ad-events es una librería pequeña de TypeScript que extrajimos de la propia medición de LoomaScale. Genera un identificador de deduplicación por conversión y entrega ese mismo valor al Meta Pixel, a Google Ads, al píxel de ChatGPT Ads y a sus Conversions API del servidor, así que una conversión reportada dos veces se cuenta una sola vez.

• Sin dependencias
• TypeScript, ESM y CJS
• Node, Bun, Deno y Edge

Por qué las conversiones se cuentan dos veces

Cómo funciona la librería

Una sola llamada reporta la conversión a todas las plataformas que configuraste y devuelve el identificador que usó, para que lo envíes a tu propio backend en el mismo manejador del clic.

1. 1El navegador genera el identificador

   Tiene que ser el navegador, porque es el lado que quizá no reporte nada. Genéralo donde ocurre el clic y el evento del servidor seguirá siendo deduplicable incluso cuando un bloqueador se coma el píxel, que es justamente el caso por el que agregaste el evento del servidor.

2. 2Cada adaptador recibe el mismo valor

   Los adaptadores de Meta, Google Ads y ChatGPT Ads lo colocan donde su plataforma lo espera y convierten el monto a la unidad que esa plataforma espera. Un adaptador cuyo píxel no se cargó no hace nada, nunca lanza un error, así que un reporte fallido jamás rompe un checkout.

3. 3El servidor lo repite

   Cuando llega el webhook del pago, la única prueba real de que el dinero se movió, el servidor envía el mismo nombre de evento y el mismo identificador. La plataforma reconoce el par y conserva una sola conversión.

import {
  createTracker,
  metaAdapter,
  googleAdsAdapter,
  openAiAdapter,
} from "ad-events/browser";

const tracker = createTracker({
  adapters: [
    metaAdapter({ eventNames: { checkout_started: "InitiateCheckout" } }),
    googleAdsAdapter({
      conversionId: "AW-123456789",
      labels: { checkout_started: "abcDEF_ghi" },
    }),
    openAiAdapter(),
  ],
});

// One id, every platform — and it is the return value, so you
// cannot forget to send it to your own backend.
const eventId = tracker.track({
  name: "checkout_started",
  value: 49,
  currency: "USD",
});

await fetch("/api/checkout", {
  method: "POST",
  body: JSON.stringify({ plan, price, eventId }),
});

import { createMetaConversionsApi } from "ad-events/server";

const meta = createMetaConversionsApi({
  pixelId: process.env.META_PIXEL_ID,
  accessToken: process.env.META_ACCESS_TOKEN,
});

await meta.send({
  eventName: "InitiateCheckout", // identical to the browser event
  eventId,                       // the id the browser minted
  email: order.email,            // normalized and hashed for you
  fbp, fbc,                      // the cookies the browser read
  customData: { value: order.price, currency: "USD" },
});

Qué cubre

• Meta Pixel y Conversions API

  Un event_id compartido, las cookies _fbp y _fbc leídas en el navegador para que el evento del servidor las lleve, y los campos de identidad normalizados y hasheados con SHA-256 igual que los hashea Meta al hacer la coincidencia. Tu propio id de usuario se hashea antes de enviarse, nunca viaja en claro.

• Google Ads

  Conversiones por gtag con deduplicación por transaction_id, una clave sincrónica e irreversible para que el mismo registro reportado desde dos páginas de retorno cuente una vez, y los identificadores de clic gclid, gbraid y wbraid tratados como un solo valor en lugar de tres columnas vacías.

• ChatGPT Ads (OpenAI)

  El píxel oaiq y el Conversions API de OpenAI, incluidas las dos cosas fáciles de equivocar: el monto como entero en centavos y un tipo de payload que no se deduce del nombre del evento. Por ahora casi no existen herramientas públicas para esta plataforma.

Atribución de primer contacto, porque el embudo dura más que la URL

Preguntas