1. Tracking

Events

Version:

Events represent actions that a site visitor performs in your app. In response to these actions, you can set up event capturing using the Cloud SDK events package. When an event is captured, all its data is sent to Sitecore and it becomes available in the various Sitecore DXP products your organization has access to.

Overview of events

The Cloud SDK lets you capture both standard events that are available out of the box and your own, custom events.

Here's an overview of the events you can send to Sitecore:

Event type

Description

Can contain extension data

Can be queued

VIEW

A standard event that tracks when the site visitor views a webpage in your app.

Content SDK and JSS apps automatically capture this event, with no coding required.

Client-side tracking function: pageView

Server-side tracking function: pageView

Yes

Yes

IDENTITY

A standard event that captures, for example, the site visitor's name, email address, and phone number when they sign up for or log in to your app.

Client-side tracking function: identity

Server-side tracking function: identity

Yes

Yes

FORM

A standard event that tracks when the site visitor views or submits a Sitecore form.

Content SDK and JSS apps automatically capture this event, with no coding required.

Client-side tracking function: form

Server-side tracking function: N/A

No

No

Order-related events

Standard events for sending orders to Sitecore CDP in real time.

Client-side tracking function: event

Server-side tracking function: event

Yes

Yes

Sitecore Search events

Standard events to track when the site visitor views or clicks a search experience. These events are sent to Sitecore Search.

Important

You can set up event capturing in search experiences using the Cloud SDK search package.

No

No

custom

A custom event that can capture any action you choose to track. For example, clicks on components and how many times a site visitor adds items to their wish list.

Client-side tracking function: event

Server-side tracking function: event

Yes

Yes

The data in the events

Part of the event data is automatically generated from the event itself, while some of it is provided by you when you set up the function that captures the event.

Automatically populated data

The following data is automatically populated:

  • The type of the captured event, such as VIEW.

    Note

    When you use the event function to send events, you have to manually provide the type of the event.

  • The Coordinated Universal Time (UTC) date and time when the event was captured, with millisecond precision.

  • Session data - the device, operating system, and web browser used for visiting the site, and the referrer URL, if any.

  • Geolocation data - city, country, region, and continent information based on the site visitor's IP address. This data is collected once per active session when the site visitor interacts with your app. It is collected from the first event in that session and is not updated again during the same session.

    Note

    The session will end as a result of inactivity after a certain amount of time. Session timeout is determined by SitecoreAI analytics identifiers.

Data provided by you

When you set up the function that captures the event, you usually pass certain data to the function in an event data object. This object accepts required and optional data that's intrinsic to the event. For example, when you set up the identity function to capture IDENTITY events, you'll usually provide the site visitor's email address, first name, and last name in the identity event data object.

Depending on the event you want to capture, in the event data object, you can also provide the extension data object.

The extension data object is for collecting non-essential, custom data about the event. You can include a maximum of 50 custom attributes of your choice in this object. After you send the event, the data in this object becomes available in Sitecore CDP and Sitecore Personalize.

Note

Not every function accepts these parameters. See the reference documentation for the parameters and the required and optional data for the various event data objects.

Options for sending events

Depending on your application requirements, you can send events from the browser (client-side tracking) or from the server (server-side tracking).

In the events package, the browser module lets you set up client-side tracking, and the server module lets you set up server-side tracking.

You can send events one by one or, when using client-side tracking, queue them and send them later in one go.

Events are exposed to the window object

If you use the browswer module to set up client-side tracking, the event-capturing functions are exposed to the window object and are accessible on window.scCloudSDK.events. This lets you run the functions outside your app's code base, in an external script that you inject into your webpage.

To achieve this, you can either run the functions directly inside the external script file, or by using a tag management system, such as Google Tag Manager.

The benefit of using an external script to capture events is that your tracking implementation becomes independent from your app's development backlog, release cycle, and potential release delays.

The JavaScript of a Sitecore Personalize web experience or web experiment is one example of an external script that runs event-capturing functions on the window object. When these scripts run in your app, they display web personalizations and capture events that occur inside them. For example, when a site visitor clicks a button in a personalized pop-up.

The following event-capturing functions are exposed to the window object:

Function name

Description

window.scCloudSDK.events.pageView

Runs the pageView function, which captures VIEW events.

window.scCloudSDK.events.identity

Runs the identity function, which captures IDENTITY events.

window.scCloudSDK.events.form

Runs the form function, which captures FORM events.

window.scCloudSDK.events.event

Runs the event function, which captures custom events.

window.scCloudSDK.events.addToEventQueue

Runs the addToEventQueue function, which adds an event object with a valid payload to the event queue.

window.scCloudSDK.events.processEventQueue

Runs the processEventQueue function, which sends all the events in the event queue, in the order they were added.

window.scCloudSDK.events.clearEventQueue

Runs the clearEventQueue function, which empties the event queue without sending any of the events.

Checking the payload

While you're setting up tracking during development, we recommend that you use your web browser's developer tools to check the payload containing all the event data that is sent to Sitecore.

You can check event payloads by opening your web browser's developer tools, and then clicking the Network tab, then pasting the following URL in the Filters field:

edge-platform.sitecorecloud.io

Doing this lists the network requests made to Sitecore.

In the list of requests, POST requests with a status of 201 Created and a name that starts with events represent the network requests that contain event data. You can check the payload by clicking one of the requests, and then clicking Payload.

Here's an example network request when a custom event named myretailsite:CLICKED_PROMO triggers:

Network requests in a web browser's developer tools.
If you have suggestions for improving this article, let us know!