Analytics tracking (ADK)

This article provides reference material for the Web store ADK analytics shared module.

The module lets add-ons emit ecommerce analytics events from custom UI locations. Events are forwarded through the same client-side pipeline that Sana already uses for standard tracking.

Note

This feature is client-side only. It does not add backend APIs, GraphQL schema, or new tracker configuration surfaces.

Prerequisites

Read Sana ADK and JavaScript APIs for how Web store vs Admin APIs are separated and how sana/<module> imports work.

Module import

Add-ons import the analytics API from the Web store ADK shared module:

import {
  trackProductClick,
  trackProductListView,
  trackAddToBasket,
  trackRemoveFromBasket,
} from 'sana/analytics';

Dispatch semantics

The track* functions from sana/analytics are action creators. They return a Redux Action and do not send analytics events on their own.

To forward an event into the analytics pipeline, dispatch the returned action:

import { useDispatch } from 'react-redux';
import { trackProductClick } from 'sana/analytics';

const dispatch = useDispatch();

dispatch(
  trackProductClick({
    product: {
      id: 'SKU-001',
      title: 'Example product',
    },
    source: { id: 'featured_widget', name: 'Featured products widget' },
  }),
);

Tracking functions

Each function returns a Redux Action. Dispatch the returned value to record the event.

`trackProductClick`

Creates a Redux action for product click tracking (for example the user selects a product in custom UI).

Argument	Type	Description
`input`	`ProductClickInput`	Clicked product and required `source`.

`trackProductListView`

Creates a Redux action for product list view tracking (for example a list of products becomes visible in custom UI).

Argument	Type	Description
`input`	`ProductListViewInput`	Displayed products and required `source`.

`trackAddToBasket`

Creates a Redux action for add to basket tracking. Supports multiple products in one event.

Argument	Type	Description
`input`	`ProductsAddToBasketInput`	Products added; `source` is optional.

`trackRemoveFromBasket`

Creates a Redux action for remove from basket tracking.

Argument	Type	Description
`input`	`ProductsRemoveFromBasketInput`	Products removed; no `source` field on this input type.

Types

`ProductClickInput`

Property	Type	Description
`product`	`ProductTrackingData`	Clicked product data.
`source`	`TrackingEventSource`	Event source context (required).

`ProductListViewInput`

Property	Type	Description
`products`	`Array<ProductTrackingData>`	Products shown in the viewed list.
`source`	`TrackingEventSource`	Event source context (required).

`ProductsAddToBasketInput`

Property	Type	Description
`products`	`Array<ProductTrackingData>`	Products added to basket in this event (batch supported).
`source`	`TrackingEventSource`	(optional) Event source context.

`ProductsRemoveFromBasketInput`

Property	Type	Description
`products`	`Array<ProductTrackingData>`	Products removed from basket in this event.

`TrackingEventSource`

Tracking event source for analytics (for example list or widget attribution).

Property	Type	Description
`id`	string	Tracking event source identifier.
`name`	string	Tracking event source name for analytics reports.

`ProductTrackingData`

Product fields accepted by analytics tracking payloads.

Property	Type	Description
`id`	string	The product unique identifier.
`title`	`string \| null`	The product title.
`ordinalNumber`	number	(optional) Ordinal position in a list, when applicable.
`variant`	`string \| null`	(optional) Selected variant identifier.
`price`	`number \| null`	(optional) Sales price for tracking.
`priceInfo`	`PriceInfo \| null`	(optional) Structured sales price info.
`quantity`	number	(optional) Quantity, when applicable.
`uom`	`object \| null`	(optional) Unit of measure for the tracked line.
`categoriesPaths`	`Array<{ categories: ProductCategories }>`	(optional) Category breadcrumbs for the product.
`productGroup`	`ProductGroup \| null`	(optional) Product group context.
`listPrice`	`number \| null`	(optional) List (base) price for tracking.
`listPriceInfo`	`PriceInfo \| null`	(optional) Structured list price info.

UoM object

Represents information about product unit of measure.

Property	Type	Description
`id`	string	UoM identifier.
`description`	`string \| null`	(optional) UoM display name or description.
`quantityStep`	number	(optional) Smallest order quantity step for this UoM.

`ProductCategories`

Product category path segment used in analytics payloads. Supports a category ID, a list of category IDs, or a list of category name objects.

Type
`string`
`Array<string>`
`Array<{ name: string }>`

`ProductGroup`

Product group reference for analytics.

Property	Type	Description
`id`	string	The product group unique identifier.
`title`	`string \| null`	(optional) The product group title.

`PriceInfo`

Structured price value used inside product tracking payloads (for example priceInfo, listPriceInfo).

Property	Type	Description
`price`	number	Tracked price value.

Table of Contents