Tracking API

Tamio tracks 14 built-in commerce and engagement events automatically, including product views, cart actions, checkout steps, purchases, search, login, sign-up, and page duration — see the full table below.

Enable tracking by pasting the Google or Meta tracking ID/snippet in the site admin under Site Settings > Tracking.

Developers can also use xScripts.tracking from merchant header or footer scripts to observe Tamio events, block or replace them, forward them to custom endpoints, or send custom events through the same consent-aware dispatcher.

For examples of how to use the tracking for custom events, see the "Examples" tab above.

Events

Event	When It Fires	GA4 Event	Meta Event
View product	Product page loads	`view_item`	`ViewContent`
View category/list	Category, listing, or search listing page loads	`view_item_list`	`ViewItemList` custom
Add to cart	Product is added to cart	`add_to_cart`	`AddToCart`
Remove from cart	Product is removed from cart	`remove_from_cart`	`RemoveFromCart` custom
View cart	Cart or checkout modal opens	`view_cart`	`ViewCart` custom
Begin checkout	Customer continues from cart into checkout	`begin_checkout`	`InitiateCheckout`
Add shipping info	Shipping step is completed	`add_shipping_info`	`AddShippingInfo` custom
Add payment info	Payment step loads	`add_payment_info`	`AddPaymentInfo`
Purchase	Thank-you page loads after a paid order	`purchase`	`Purchase`
Search	Search results are shown or submitted	`search`	`Search`
Login	Portal login succeeds	`login`	`Login` custom
Sign up	Portal registration succeeds	`sign_up`	`CompleteRegistration`
Page duration milestone	Visible page time reaches a milestone	`page_duration`	`PageDuration` custom
Page duration exit	Visitor leaves or an attention-taking overlay opens after minimum visible time	`page_duration_end`	`PageDurationEnd` custom

view_item fires only on product pages and carries the product details — it is a reliable marker for "this is a product page" even when the URL has no fixed pattern.

Page duration

Default milestones are 5, 10, 30, 60, 120, and 300 seconds. Time is measured as active time — it pauses when the tab is in the background.

Every page_duration event uses the same name but carries parameters that tell the milestones apart:

Parameter	Example	Meaning
`milestone_seconds`	`30`	The milestone that fired (`5`, `10`, `30`, ...)
`event_label`	`"30_seconds"`	The same milestone as a label
`duration_seconds`	`32`	Actual visible (active) time when it fired
`page_path`	`/sv/product/blue-shirt`	Page the event came from
`final`	`false`	`true` only on the `page_duration_end` exit event

In GA4 reports you separate the milestones by filtering on milestone_seconds (register it once as a custom dimension) — you do not need a different event name per milestone. For a dedicated Google Ads conversion you do need a distinct event name, since Ads matches on the name; see the product-engagement example in the tab above.

Observe events — `onEvent(handler)`

Registers a handler that runs for every native and custom event, after Tamio has resolved consent and active destinations. Returns an unsubscribe function; offEvent(handler) also removes it.

The handler receives an event object:

Field / method	Description
`type`	Generic event name, such as `add_to_cart` or `purchase`
`data`	Normalized event payload
`targets`	Destinations that will receive the event, such as `["google"]` or `["google", "facebook"]`
`event.preventDefault()`	Stop the event from being sent to any destination
`event.preventDefaultFor(platform)`	Stop the event for one destination only — `'google'` or `'facebook'`

Returning false from the handler is the same as calling event.preventDefault().

Send custom events — `track(name, data, options)`

Adds a merchant-defined event to the same pipeline as native events, so it still passes consent checks and destination routing.

name — generic event name (string).
data — plain JSON payload.
options.platforms — optional array restricting destinations, e.g. ['google']. Without it, the event goes to every consented destination.

trackCustom is an alias of track.

Block or replace events

Because an onEvent handler can both cancel an event and emit a new one with track, you can replace a built-in event with your own: block the original (or keep it) and send a cleaner, purpose-named version. This is the basis of the product-engagement conversion recipe.

Call	Effect
`event.preventDefault()` / `return false`	Stop the event for all destinations
`event.preventDefaultFor('google')`	Stop the event for Google only (GA4 and Google Ads)
`event.preventDefaultFor('facebook')`	Stop the event for Meta only

google covers both GA4 and Google Ads, so blocking it removes the event from GA4 reports as well.

Notes

onEvent is for observing, blocking, or replacing events.
track is for adding merchant custom events.
Use generic event names and plain JSON payloads.
Scripts can go in the header or footer — handlers only run after Tamio initializes, so they never miss events.
Avoid overwriting window.xScripts or xScripts.tracking.