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 you can extend it for advanced tracking needs.

Setup

The Tracking Service is installed but disabled by defaultwhen installing Sitecore Headless Services.

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 help enable CORS support for the Tracker. It is good practice to use one API key for each app, but you can use the same API key for all its services.

Tracking events

You can track events using the endpoint /sitecore/api/jss/track/event?sc_apikey=[key].

The endpoint accepts POST requests with JSON payloads.

The following table shows the types of events you can track and the payload you must send to the Tracking Service endpoint:

Event type

Payload

Goal

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

Outcome

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

Page event

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

Campaign

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

Event

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

Tip

If you develop a JSS application, you can use the JSS Tracking API.

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. To see your testing results more efficiently, you can enable the indexing of anonymous contacts.

Important

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 you extend it 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.

The pipeline processor TrackEvent method must:

  • If it can not handle the incoming request, return. Returning in a pipeline processor without other actions resumes the pipeline (continues to the next processor).

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

  • If it can handle the request but encounters an error, call args.ReportError() and return.