Canonical events
One fixed vocabulary in your code. adscapi maps each name to the platform's native event (or passes the string through where the platform accepts custom events). You never learn twenty-six event enums.
The vocabulary
Use these names on ConversionEvent.name. Type is CanonicalEventName | string — custom strings are allowed.
| Name | Typical moment |
|---|---|
page_view | Landing / key page load |
lead | Form submit, demo request |
signup_start | Began registration flow |
signup | Account created / registration complete |
checkout_created | Checkout initiated |
purchase | Paid order / subscription |
reply_generated | Product-specific engagement (e.g. AI reply) |
upgrade_clicked | Upgrade CTA clicked |
ts
type CanonicalEventName = | 'page_view' | 'lead' | 'signup_start' | 'signup' | 'checkout_created' | 'purchase' | 'reply_generated' | 'upgrade_clicked';
How mapping works
- Each platform ships an
EventNameMap— a partial record of canonical → native - Names with no entry (often
signup_start,reply_generated,upgrade_clicked) fall through as the raw canonical string, which platforms that accept custom events keep; fixed-enum platforms may reject them - Some platforms (Bing offline goals, X event ids) are advertiser-defined — the map is empty or inert and the string you send must match what you configured in the ads UI
Sample mappings
A slice of major platforms. Omitted cells mean passthrough / no standard fit.
| Canonical | meta | tiktok | ga4 | snapchat | chatgpt | |||
|---|---|---|---|---|---|---|---|---|
page_view | PageView | ViewContent | page_view | page_visit | KEY_PAGE_VIEW | PAGE_VIEW | PAGE_VISIT | page_viewed |
lead | Lead | SubmitForm | generate_lead | lead | LEAD | SIGN_UP | LEAD | lead_created |
signup | CompleteRegistration | CompleteRegistration | sign_up | signup | SIGN_UP | SIGN_UP | SIGN_UP | registration_completed |
checkout_created | InitiateCheckout | InitiateCheckout | begin_checkout | initiate_checkout | START_CHECKOUT | START_CHECKOUT | ADD_TO_CART | checkout_started |
purchase | Purchase | Purchase | purchase | checkout | PURCHASE | PURCHASE | PURCHASE | order_created |
Example
ts
await ads.conversions.track({
name: 'purchase', // canonical — mapped per platform
value: 49,
currency: 'USD',
user: { email: 'jane@example.com' },
consent: { adUserData: true, adPersonalization: true },
});
// Custom strings pass through where the platform allows them:
await ads.conversions.track({
name: 'trial_started',
consent: { adUserData: true, adPersonalization: true },
});