The catalogue
| Category | Events | Default purposes |
|---|---|---|
| engagement | page_view, view_content, search, download | analytics |
| auth | sign_up, login | analytics |
| lead | generate_lead, contact, book_appointment | analytics, marketing |
| commerce | view_item_list, select_item, view_item, add_to_wishlist, add_to_cart, remove_from_cart, view_cart, begin_checkout, add_shipping_info, add_payment_info, purchase, refund | analytics, marketing |
| subscription | subscribe, start_trial | analytics, marketing |
Names follow the GA4 recommended-event vocabulary where one exists, because it is the most widely implemented data-layer shape and the SDK can observe GA4-style dataLayer pushes directly. Categories decide the default consent purposes: commerce, lead and subscription events are conversion signals that advertising platforms want, so they require the marketing purpose to reach an advertising destination; engagement and auth events are analytics by default.
Properties
Every event carries the envelope: event id, timestamp, URL (with click ids scrubbed), referrer, title, consent record, source, and — when consent allows — anonymous id, session id, user id and hashed identifiers.
Commerce events add a typed commerce block: currency, value, transaction_id, coupon, shipping, tax, and items[] with item_id, item_name, price, quantity, item_category, item_brand, item_variant. refund carries the original transaction_id and a negative or partial value.
Lead and subscription events use a small property set: lead_type, form_id, plan, interval, trial_days, value where a documented value exists.
Anything else goes into props, which is validated against the site's schema: unknown keys are reported as findings, free text is scanned for personal data, and nested objects are redacted rather than forwarded.
Custom events
Custom names are allowed when they match ^[a-z][a-z0-9_]{2,39}$, do not collide with a standard name and are declared in the tracking plan. Undeclared custom events are accepted, counted and reported as schema findings so the plan can be updated deliberately; they are not delivered to advertising destinations until mapped.
Translation to vendors
Because the vocabulary is fixed, each connector ships a default mapping:
| Canonical | Meta | Google Ads | GA4 | TikTok | Snapchat | ||
|---|---|---|---|---|---|---|---|
view_item | ViewContent | — | view_item | ViewContent | — | page_visit | VIEW_CONTENT |
add_to_cart | AddToCart | — | add_to_cart | AddToCart | — | add_to_cart | ADD_CART |
begin_checkout | InitiateCheckout | — | begin_checkout | InitiateCheckout | — | — | START_CHECKOUT |
purchase | Purchase | conversion action | purchase | CompletePayment | conversion rule | checkout | PURCHASE |
generate_lead | Lead | conversion action | generate_lead | SubmitForm | conversion rule | lead | SIGN_UP |
sign_up | CompleteRegistration | conversion action | sign_up | CompleteRegistration | conversion rule | signup | SIGN_UP |
subscribe | Subscribe | conversion action | — | Subscribe | conversion rule | — | SUBSCRIBE |
start_trial | StartTrial | conversion action | — | StartTrial | conversion rule | — | START_TRIAL |
A dash means the vendor has no standard equivalent; you can map to a custom vendor event or leave the row disabled. Every default is editable per destination, and every change is versioned and shows in the publish diff.
Rules that keep the plan honest
- One event per user action.
purchasefires once per order, from whichever source is authoritative for that site (browser, shop webhook or server), with the same event id or order id on every path. - Values come from the source system. There is no default value; an unmapped value is
null, and a vendor that requires one rejects the row visibly. - Refunds are events, not edits. A
refundreferences the original transaction; the originalpurchaseis never rewritten. - Names are lowercase snake case. Vendor casing (
CompletePayment,PURCHASE) is the connector's concern.