JSS Tracking API

Abstract

Overview of the client-side implementation of the Sitecore Headless Services Tracker

The client-side implementation for the Headless Services Tracker is the @sitecore-jss/sitecore-jss-tracking NPM package. This package 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 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

{
    goalId: "<goal ID>"
}

OutcomeInstance

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

PageViewInstance

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

CampaignInstance

{
    campaignId: "<campaign ID>"
}

EventInstance

{
    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 using 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