Tracking API

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

Tamio then 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.

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

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

Default page-duration milestones are 5, 10, 30, 60, 120, and 300 seconds.

Observe Tamio Events

Use onEvent to listen to native Tamio tracking events and merchant custom events after Tamio has resolved consent and active destinations.

HTML

1 <script>
2 xScripts.tracking.onEvent(function (event) {
3   console.log('Tracking event:', event.type, event.data, event.targets);
4 });
5 </script>

The event object contains:

Field	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"]`

Forward Events To A Custom Endpoint

Use onEvent when you want your own analytics endpoint to receive the same events Tamio tracks.

HTML

1 <script>
2 var endpoint = 'https://example.com/tracking/tamio';
3 
4 xScripts.tracking.onEvent(function (event) {
5   var payload = {
6     event: event.type,
7     data: event.data,
8     targets: event.targets,
9     page_url: window.location.href,
10     page_path: window.location.pathname,
11     sent_at: new Date().toISOString()
12   };
13 
14   try {
15     if (navigator.sendBeacon) {
16       var blob = new Blob([JSON.stringify(payload)], { type: 'application/json' });
17       if (navigator.sendBeacon(endpoint, blob)) return;
18     }
19 
20     fetch(endpoint, {
21       method: 'POST',
22       headers: { 'Content-Type': 'application/json' },
23       body: JSON.stringify(payload),
24       keepalive: true
25     }).catch(function () {});
26   } catch (error) {
27     console.warn('Custom tracking endpoint failed:', error);
28   }
29 });
30 </script>

Transform And Forward Events

You can also listen for a Tamio event, build your own payload, and send that version to a custom endpoint.

HTML

1 <script>
2 var endpoint = 'https://example.com/tracking/purchase';
3 
4 xScripts.tracking.onEvent(function (event) {
5   if (event.type !== 'purchase') return;
6 
7   var payload = {
8     order_id: event.data.transaction_id,
9     total: event.data.value,
10     currency: event.data.currency,
11     product_ids: (event.data.items || []).map(function (item) {
12       return item.item_id;
13     }),
14     product_count: (event.data.items || []).length,
15     source: 'tamio',
16     page_path: window.location.pathname
17   };
18 
19   fetch(endpoint, {
20     method: 'POST',
21     headers: { 'Content-Type': 'application/json' },
22     body: JSON.stringify(payload),
23     keepalive: true
24   });
25 });
26 </script>

Track Specific Pages

Use page rules when a merchant wants a custom event on specific paths.

HTML

1 <script>
2 var pageEvents = [
3   {
4     match: /^\/(en|sv)\/wholesale(\/|$)/,
5     event: 'view_wholesale_page',
6     data: { area: 'wholesale' }
7   },
8   {
9     match: /^\/(en|sv)\/campaign\/summer-sale(\/|$)/,
10     event: 'view_summer_campaign',
11     data: { campaign: 'summer-sale' }
12   }
13 ];
14 
15 pageEvents.forEach(function (rule) {
16   if (!rule.match.test(window.location.pathname)) return;
17 
18   xScripts.tracking.track(rule.event, Object.assign({}, rule.data, {
19     page_location: window.location.href,
20     page_path: window.location.pathname,
21     page_title: document.title || ''
22   }));
23 });
24 </script>

Send Custom Events

Use track to add merchant-defined events to the same tracking pipeline. These events still go through Tamio consent checks and destination routing.

HTML

1 <script>
2 xScripts.tracking.track('merchant_custom_event', {
3   label: 'Example custom event',
4   value: 123,
5   currency: 'SEK',
6   page_path: window.location.pathname
7 });
8 </script>

Derive Custom Events From Tamio Events

You can listen to a native Tamio event and create a new custom event from it. The custom event is sent through the normal Tamio tracking pipeline to configured destinations such as GA4 and Meta.

HTML

1 <script>
2 xScripts.tracking.onEvent(function (event) {
3   if (event.type !== 'purchase') return;
4 
5   xScripts.tracking.track('high_value_purchase', {
6     transaction_id: event.data.transaction_id,
7     value: event.data.value,
8     currency: event.data.currency,
9     product_count: (event.data.items || []).length
10   });
11 });
12 </script>

You can use the same pattern for other source events:

HTML

1 <script>
2 xScripts.tracking.onEvent(function (event) {
3   if (event.type !== 'add_to_cart') return;
4 
5   xScripts.tracking.track('merchant_add_to_cart', {
6     value: event.data.value,
7     currency: event.data.currency,
8     source_event: event.type
9   });
10 });
11 </script>

Notes

onEvent is for observing events.
track is for adding merchant custom events.
Use generic event names and plain JSON payloads.
Avoid overwriting window.xScripts or xScripts.tracking.

1	<script>
2	xScripts.tracking.onEvent(function (event) {
3	console.log('Tracking event:', event.type, event.data, event.targets);
4	});
5	</script>

1	<script>
2	var endpoint = 'https://example.com/tracking/tamio';
3
4	xScripts.tracking.onEvent(function (event) {
5	var payload = {
6	event: event.type,
7	data: event.data,
8	targets: event.targets,
9	page_url: window.location.href,
10	page_path: window.location.pathname,
11	sent_at: new Date().toISOString()
12	};
13
14	try {
15	if (navigator.sendBeacon) {
16	var blob = new Blob([JSON.stringify(payload)], { type: 'application/json' });
17	if (navigator.sendBeacon(endpoint, blob)) return;
18	}
19
20	fetch(endpoint, {
21	method: 'POST',
22	headers: { 'Content-Type': 'application/json' },
23	body: JSON.stringify(payload),
24	keepalive: true
25	}).catch(function () {});
26	} catch (error) {
27	console.warn('Custom tracking endpoint failed:', error);
28	}
29	});
30	</script>

1	<script>
2	var pageEvents = [
3	{
4	match: /^\/(en\|sv)\/wholesale(\/\|$)/,
5	event: 'view_wholesale_page',
6	data: { area: 'wholesale' }
7	},
8	{
9	match: /^\/(en\|sv)\/campaign\/summer-sale(\/\|$)/,
10	event: 'view_summer_campaign',
11	data: { campaign: 'summer-sale' }
12	}
13	];
14
15	pageEvents.forEach(function (rule) {
16	if (!rule.match.test(window.location.pathname)) return;
17
18	xScripts.tracking.track(rule.event, Object.assign({}, rule.data, {
19	page_location: window.location.href,
20	page_path: window.location.pathname,
21	page_title: document.title \|\| ''
22	}));
23	});
24	</script>

1	<script>
2	xScripts.tracking.track('merchant_custom_event', {
3	label: 'Example custom event',
4	value: 123,
5	currency: 'SEK',
6	page_path: window.location.pathname
7	});
8	</script>

1	<script>
2	xScripts.tracking.onEvent(function (event) {
3	if (event.type !== 'purchase') return;
4
5	xScripts.tracking.track('high_value_purchase', {
6	transaction_id: event.data.transaction_id,
7	value: event.data.value,
8	currency: event.data.currency,
9	product_count: (event.data.items \|\| []).length
10	});
11	});
12	</script>

1	<script>
2	xScripts.tracking.onEvent(function (event) {
3	if (event.type !== 'add_to_cart') return;
4
5	xScripts.tracking.track('merchant_add_to_cart', {
6	value: event.data.value,
7	currency: event.data.currency,
8	source_event: event.type
9	});
10	});
11	</script>