Tracking Service

Abstract

Track Events, Goals, Outcomes, Campaigns, and Page/Route Views in headless front-end applications

The Tracking Service provided by Headless Services is an analytics tracking REST API that allows pushing Sitecore analytics events to the xDB based on client-side behavior. By default, it supports tracking Events, Goals, Outcomes, Campaigns, and Page/Route Views and it can be extended for advanced tracking needs.

Setup

When installing Sitecore Headless Services, the Tracking service is installed but disabled by default.

To enable the Tracker, set the Sitecore.JSS.TrackerServiceEnabled setting to true in a configuration patch file, for example:

<configuration>
  <sitecore>
    <settings>
      <setting name="Sitecore.JSS.TrackerServiceEnabled" value="true" />
    </settings>
  </sitecore>
</configuration>

The tracker utilizes SSC API keys just like other services. The API keys are used to enable CORS support for the Tracker. It is good practice to use one API key for each app, and it can be shared for all services the app uses.

Indexing and viewing contact and tracking data

You can view the data pushed by your tracking code in the Experience Profile.

By default, Sitecore does not index anonymous contact data, which means non-identified users do not have their data in the Experience Profile. For testing purposes, you might want to enable indexing of anonymous contacts to more easily see the results of your testing.

Warning

We do not recommend Indexing anonymous contacts in production environments.

The Tracker Service does not support identifying contacts out of the box but you can extend it.

Sitecore does not store or index the tracked data into the Experience Profile before the end of the user session. To end the user session, invoke the endpoint /sitecore/api/jss/track/flush.

Extending the tracker

The tracker is a tracking data conduit and can be extended as needed. The trackEvent pipeline, defined in App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.Tracker.config, is responsible for handling incoming tracking requests.

You can use a configuration patch to include new or replaced pipeline processors.

Processors must derive from Sitecore.JavaScriptServices.Tracker.Pipelines.TrackEvent<T>, where T is a C# type to deserialize the incoming JSON to.

The pipeline processor TrackEvent method must:

  • Return if the incoming request was not something it can handle. Returning in a pipeline processor without other actions resumes the pipeline (continues to the next processor).

  • Call args.HasBeenTracked() and abort the pipeline if it can handle the incoming request. Aborting the pipeline stops it from processing further, because some actions might have already been taken.

  • Call args.ReportError() and return if it can handle the request, but encountered an error doing so.