Collecting data using events

Version:

Using the events package of the Cloud SDK, you can collect data about your site visitors in real time. Data collection happens when the visitor performs an action on your site, for example, views a webpage, clicks a button, or submits an XM Cloud form. In response to these actions, you can capture events and send them with all their data to Sitecore.

Events

Events represent actions that a site visitor performs in your app. The Cloud SDK lets you capture both standard events that are available out of the box and your own, custom events.

For example, the VIEW event is a standard event that represents a site visitor's action of viewing a webpage. VIEW events are automatically captured in your JSS Next.js app, no coding required. The VIEW event automatically triggers every time a site visitor loads the page, and then the event with all its data is sent to Sitecore.

Using custom events, you can track a site visitor's interactions with unique elements on your page. For example, you can capture the site visitor's action of clicking a Promo component on your page by creating a custom event and giving it a custom name such as myretailsite:CLICKED_PROMO. You can capture this event every time a site visitor clicks the Promo. Then, the event with all its data is sent to Sitecore.

The data in the events

When an event triggers, all its data is sent to Sitecore. Some of this data is automatically populated, while other data is provided by you when you run the function that sends the event.

The following data is automatically populated:

The event name, such as VIEW, and the date and time when the event triggered.
Session data - the device, operating system, and web browser used for visiting the site, and the referrer URL, if any.
Geolocation data - city, country, 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 within the same session.

Note

The session ends as a result of inactivity after a certain amount of time. Session length is determined when an XM Cloud user creates and assigns site identifiers.

When you run the function that sends the event, you pass certain data to the function. Depending on the function parameters, this can be:

The data you provide in the eventData object. The eventData object contains required and optional data that's intrinsic to the event. For example, when you run the identity function to send an IDENTITY event, you'll usually include the site visitor's email address, first name, and last name in this object.
The data you provide in the optional extensionData object. The extensionData 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.

Note

Not every function accepts these parameters. See the reference documentation for the parameters and required and optional data of all the event functions.

Options for sending events

In the events package, the browser module lets you send events from the browser (client-side tracking), and the server module lets you send them from the server (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.

Overview of events

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

Event	Type	Description	Client-side tracking function	Server-side tracking function	Can contain custom event data using `extensionData`	Can be queued
`VIEW`	standard	Captures the site visitor's action of viewing a webpage in your app. Your JSS Next.js app automatically captures this event, no coding required.	`pageView`	`pageView`	Yes	Yes
`IDENTITY`	standard	Captures, for example, the site visitor's name, email address, and phone number when they sign up for or log in to your app.	`identity`	`identity`	Yes	Yes
`FORM`	standard	Captures the site visitor's action of viewing or submitting an XM Cloud form. Your JSS Next.js app automatically captures this event, no coding required.	`form`	N/A	No	No
custom	custom	Can capture any action you choose to track. For example, clicks on components and how many times a visitor adds items to their wish list.	`event`	`event`	Yes	Yes

Viewing the collected data

The collected data is used across your Sitecore apps. You can view some of the data in, for example, analytics dashboards in XM Cloud Pages Analyze and XM Cloud Analytics.

Behind the scenes, it's Sitecore Customer Data Platform (CDP) that captures and stores all the collected data. If you have Sitecore CDP, you can view the data there in full detail using the site visitor's browser ID. The browser ID is a universally unique identifier (UUID) that Sitecore CDP assigns to every site visitor of your site. It associates sessions and events with the respective site visitor. You can view the collected data in Sitecore CDP by clicking Guests, and in the Search field, entering the bid: prefix plus the site visitor's browser ID.

For example: bid: a38b230c-11eb-4cf9-8d5d-274e9f344925.

Then, Sitecore CDP lists the guest profile for the site visitor. In the guest profile, you can find detailed session and event data about your site visitor.

Working with the collected data

Marketers at your organization can act on the collected data in the various Sitecore apps.

Sitecore app	How to use the data
XM Cloud Pages	View site and page insights and trends in the analytics dashboard. Create audiences to personalize user experiences.
XM Cloud Analytics	View analytics for site visitor engagement with XM Cloud forms.
Sitecore CDP	View site visitor details in guest profiles. Build segments of site visitors. Export site visitor data to activate audiences in external systems. View performance metrics in prebuilt analytics dashboards.
Sitecore Personalize	Run experiments to determine which content resonates the most with each site visitor. Create personalized content.

If you have suggestions for improving this article, let us know!