JSS Tracking API

Version: 20.x

JSS provides a client-side implementation for the Headless Services Tracker through the JSS tracking module. The JSS tracking module is a lightweight wrapper around the Tracking Service (TS) that provides a simple promise-based API and support for TypeScript typings to make it easy to use.

The tracking module is a submodule of the @sitecore-jss/sitecore-jss NPM package. You import it as follows:

RequestResponse
import { trackingApi } from '@sitecore-jss/sitecore-jss/tracking

The Tracking API ships with TypeScript typings, so if you use TypeScript-aware editors, such as VS Code, annotated code completion is available.

Note

The Tracking API automatically disables itself during server-side rendering to avoid double-counting when rehydrated on the client-side.

Event types

You can use the JSS Tracking API to track events, goals, outcomes, campaigns, and page/route views.

The JSS Tracking API provides the following event-type interfaces:

Even type

Event properties

GoalInstance
RequestResponse
{
    goalId: "<goal ID>"
}

OutcomeInstance
RequestResponse
{
    outcomeId: "<goal ID>", 
    currencyCode: "<currency code>",
    monetaryValue: "<monetary value>"
}

PageViewInstance
RequestResponse
{
    pageId: "<page ID>",
    url: "<page URL>"
}

CampaignInstance
RequestResponse
{
    campaignId: "<campaign ID>"
}

EventInstance
RequestResponse
{
    eventId: "<event-value>"
}

Tracking page views

The tracking API supports tracking arbitrary page view events, which can be useful for tracking route changes that do not involve a Layout Service request, such as cached or custom routes.

When tracking page views, keep in mind that:

  • Requests to the Layout Service track a page view by default. You can disable this by adding tracking=false to the Layout Service request query string (configurable via the RestLayoutService class in JSS apps). Disabling Layout Service tracking might make sense if you want to handle all page tracking using the JSS Tracking API.

  • Page view events require a Sitecore Item ID to track against, even though the URL tracked is arbitrary. If tracking non-item-based routes, you must create surrogate items to track against.

Limitations

Do you have some feedback for us?

If you have suggestions for improving this article,