Відкритий код

Один event_id для браузера й вашого сервера

ad-events — невелика бібліотека TypeScript, яку ми виділили з власної системи вимірювання LoomaScale. Вона створює один ідентифікатор дедуплікації на конверсію й передає те саме значення до Meta Pixel, Google Ads, пікселя ChatGPT Ads і до їхніх серверних Conversions API — тому конверсія, про яку повідомили двічі, рахується один раз.

• Жодних залежностей
• TypeScript, ESM і CJS
• Node, Bun, Deno і Edge

Чому конверсії рахуються двічі

Як працює бібліотека

Один виклик повідомляє про конверсію всім налаштованим платформам і повертає використаний ідентифікатор, щоб ви могли передати його на власний бекенд у тому самому обробнику кліку.

1. 1Ідентифікатор створює браузер

   Саме браузер, бо це та сторона, яка може не повідомити зовсім. Створіть ідентифікатор там, де відбувається клік, і серверна подія залишиться придатною до дедуплікації навіть тоді, коли блокувальник з'їв піксель — а це і є той випадок, для якого ви додавали серверну подію.

2. 2Кожен адаптер отримує те саме значення

   Адаптери Meta, Google Ads і ChatGPT Ads кладуть його туди, де його очікує їхня платформа, і переводять суму в потрібну одиницю. Адаптер, чий піксель не завантажився, просто нічого не робить і не кидає винятку — тому невдале повідомлення ніколи не зламає оформлення замовлення.

3. 3Сервер повторює його

   Коли надходить вебхук про оплату — єдине справжнє підтвердження, що гроші прийшли, — сервер надсилає ту саму назву події й той самий ідентифікатор. Платформа розпізнає пару й залишає одну конверсію.

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

Що вона охоплює

• Meta Pixel і Conversions API

  Спільний event_id, куки _fbp і _fbc, прочитані в браузері, щоб їх несла серверна подія, а також поля ідентичності, нормалізовані та захешовані SHA-256 так само, як їх хешує Meta під час зіставлення. Ваш власний ідентифікатор користувача хешується перед надсиланням і ніколи не йде у відкритому вигляді.

• Google Ads

  Конверсії через gtag із дедуплікацією за transaction_id, синхронний незворотний ключ, щоб та сама реєстрація, про яку повідомили дві сторінки повернення, рахувалася один раз, і клік-ідентифікатори gclid, gbraid і wbraid як одне значення замість трьох порожніх стовпців.

• ChatGPT Ads (OpenAI)

  Піксель oaiq і Conversions API від OpenAI, разом із двома речами, у яких легко помилитися: сума цілим числом у центах і тип корисного навантаження, який не випливає з назви події. Публічних інструментів для цієї платформи поки майже немає.

Атрибуція за першим дотиком, бо воронка живе довше за URL

Питання