---
title: "JSS Tracking API"
slug: "jss-tracking-api"
abstract: "Overview of the client-side implementation of the Sitecore Headless Services Tracker"
---
# JSS Tracking API

JSS provides a client-side implementation for the [Headless Services Tracker](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/tracking-service.html "Tracking Service") 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:

```text
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`:

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

```

- `OutcomeInstance`:

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

```

- `PageViewInstance`:

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

```

- `CampaignInstance`:

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

```

- `EventInstance`:

```csharp
{
    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

The JSS Tracking API has the following limitations:

- The JSS application must [use the REST Layout API provided by JSS](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/fetch-layout-data-with-the-jss-rest-layout-service.html "Fetch layout data with the JSS REST Layout Service").
- Because tracking data is submitted directly to a Sitecore service, you cannot use the JSS tracking API in [disconnected mode](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/start-a-jss-app-in-disconnected-mode.html "Start a JSS app in disconnected mode").
- The JSS tracking API can not work if global and session cookies are not generated.

> [!important]
> From Sitecore 10.0.1, Sitecore sets the Secure flag on all cookies by default. This can impact JSS local development in Connected and Headless modes, as the proxied Sitecore cookies (including analytics cookies) are rejected by the browser if your application is not running under HTTPS, and therefore visits are not tracked and content might not be personalized. To work around this, you can do one of the following:
>
> -   Enable HTTPS in your local environment by modifying the node server, using a local reverse proxy, or using a service such as ngrok. If you are running Sitecore in containers for development, you can make use of the Traefik reverse proxy that is provided in the `docker-compose` environment.
>
> -   Transform the Sitecore `Web.config` as follows:
>
> -   In the `httpCookies` configuration, set `requireSSL` to `false` and `sameSite` to `Unspecified`.
>
> -   In the `sessionState` configuration, set `cookieSameSite` to `Unspecified`.
>
>
> We do not recommend this workaround in production environments.