Events and attribution
What sorai-js sends, where it sends it, and how a sale gets credited to the campaign that earned it.
Every event goes to Sorai, which counts it in the store's analytics, and to
each pixel you gave init(): Meta, TikTok, Google Analytics 4 and a
dataLayer push for Google Tag Manager.
Standard events
| Event | Sent when |
|---|---|
PageView | init() runs on a page with a page id. |
ViewContent | A <sorai-buy> or <sorai-price> for a product appears, once per product per page load. |
InitiateCheckout | Checkout opens for a product, once per product per tab session. |
InitiateCheckout stays in Sorai's own analytics and is not forwarded to
your pixels; the ad platforms hear about checkouts and purchases from
Sorai's server instead.
On a page that shows a product without the custom elements, send its
ViewContent yourself. It gets the same id and the same once per page
deduplication as the elements:
Sorai.track("ViewContent", { product_id: "0199b0f0-0000-7000-8000-000000000021" });Custom events
Any other name is a custom event, with whatever properties you pass:
Sorai.track("AddedToWishlist", { product_id: "0199b0f0-0000-7000-8000-000000000021" });A Meta standard event name is sent to Meta as a standard event; anything else as a custom one.
Counting each event once
When a sale or a view is reported to Meta or TikTok from both the browser
and Sorai's server, the platform has to recognise the two as one. So
PageView and ViewContent get deterministic ids built from the tab
session and the page or product:
PageView:{session}-{page}-pvViewContent:{session}-{product}-vc
The server sends the same ids, and the platform counts the event once. Custom events get a random id, because the server sends no copy of them.
Sessions and attribution
- Session. A random id in
sessionStorage(_sorai_sid), one per tab. - Visitor. A random id in a first-party cookie (
_sorai_vid) that lasts a year, so a new tab or a return visit is the same visitor. - Attribution. Recorded once, at the first
init()that finds no attribution stored: theutm_*parameters,fbclid,ttclid, the referrer and the landing page. It is kept in a first-party cookie (_sorai_attr) for 90 days and never overwritten by a later visit: the first touch wins. - Referral code. A visit that arrives with
?ref=CODEstores the code for 30 days (_sorai_ref). Here the last click wins: a new code replaces the old one and restarts the 30 days.
The Meta, TikTok and Google Analytics browser ids (_fbp, _ttp and _ga)
are read from their cookies each time an event is sent, because those
scripts may not have run yet when init() did. fbclid is also stored in
the fb.1.{timestamp}.{fbclid} form Meta expects.
Attribution and the referral code travel with the buyer into checkout, so the order records both.