Open source

One event_id across the browser and your server

ad-events is a small TypeScript library we extracted from LoomaScale's own tracking. It mints one deduplication id per conversion and hands the same value to the Meta Pixel, Google Ads, the ChatGPT Ads pixel and their server-side Conversions APIs — so a conversion reported twice is counted once.

• Zero dependencies
• TypeScript, ESM and CJS
• Node, Bun, Deno and Edge

Why conversions get counted twice

How the library works

One call reports a conversion to every platform you configured, and returns the id it used so you can forward it to your own backend in the same click handler.

1. 1The browser mints the id

   It has to be the browser, because the browser is the side that might not report at all. Mint it where the click happens and the server event stays deduplicable even when a blocker eats the pixel — which is the exact case you added the server event for.

2. 2Every adapter gets the same value

   The Meta, Google Ads and ChatGPT Ads adapters each put it where their platform expects it, and convert the money to the unit their platform expects. An adapter whose pixel never loaded is a no-op, never an exception, so a failed report can never break a checkout.

3. 3The server replays it

   When the payment webhook fires — the only real proof money moved — the server sends the same event name and the same id. The platform recognises the pair and keeps one conversion.

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" },
});

What it covers

• Meta Pixel and Conversions API

  Shared event_id, the _fbp and _fbc cookies read in the browser for the server event to carry, and identity fields normalized and SHA-256 hashed the way Meta hashes them when matching. Your own user id is hashed before it is sent, never raw.

• Google Ads

  Conversions through gtag with transaction_id deduplication, a synchronous non-reversible key so the same signup reported from two return pages counts once, and the gclid, gbraid and wbraid click ids handled as one value instead of three nullable columns.

• ChatGPT Ads (OpenAI)

  The oaiq pixel and the OpenAI Conversions API, including the two things that are easy to get wrong: money as integer cents, and a payload type that does not follow from the event name. There is almost no public tooling for this platform yet.

First-touch attribution, because the funnel outlives the URL

Questions