Set up IDENTITY events

Version:

You can use the Cloud SDK events package to capture IDENTITY events. IDENTITY events are typically captured in registration, login, and signup forms and are used to resolve the identity of an anonymous site visitor of your app.

JSS Next.js

In this topic, you'll start capturing events on the browser side, in the out-of-the-box Promo component in a JSS Next.js app (JSS version 22.2). Note that in production, you will most likely capture IDENTITY events in forms, not in the Promo component. This topic shows how to set up the event so you can later capture them in the components of your choice.

Before you begin

Make sure your SitecoreAI site has analytics identifiers.
Make sure your SitecoreAI site's webpage has a component to capture IDENTITY events from. This webpage must be published so the component appears on the website. This walkthrough uses the Promo component as an example.
Make sure you're ready to start development with the Cloud SDK.
In your code editor, open your JSS Next.js app folder.

To capture IDENTITY events on the browser side:

In Promo.tsx, at the top of the file, import the identity function from the browser module of the events package:
import { identity } from "@sitecore-cloudsdk/events/browser";
In Promo.tsx, in the Default component, within the return statement, add a React onClick event handler to the topmost JSX element:
// ... return ( <div onClick={handleClick} className={"..."} id={"..."} > {/*...*/} )
Note

In production, place the event listener on a clickable element such as a <button>, instead of a <div>.

In the Default component, on the first line of the function body, paste the following code, then save your changes:

function handleClick() {
  identity({
    identifiers: [
      {
        id: "<YOUR_ID>", // example: "[email protected]"
        provider: "<YOUR_PROVIDER>" // example: "email"
      }
    ]
  });
  console.log("Sent IDENTITY event.");
}

This code sends an IDENTITY event every time the Promo component is clicked.

Tip

In production, we recommend you pass your correct identity system data and pass other event data to the identity function to make sure that your web app captures rich event data.

In your terminal, enter npm run start:production to start your JSS Next.js app.

Tip

If your app fails to compile due to linting errors, consider disabling ESLint rules.
In your web browser, navigate to your JSS Next.js app, typically at http://localhost:3000.
In your web browser's developer tools, on the Network tab, in the Filter field, paste the following URL: edge-platform.sitecorecloud.io.

Doing this lists the network requests made to Sitecore.
Reload your webpage to start recording network activity.
On your webpage, click the Promo component.

The click triggers the IDENTITY event.
In the developer tools, on the Network tab, in the list of requests, click the last POST request with a status of 201 Created and a name that starts with events.

This is the network request made when you clicked the Promo, and it contains the event data for the IDENTITY event that you captured.
In the request details pane, click the Payload tab for the request.
In the request payload, copy the value of the browser_id key. You'll use it to find the captured events in your Sitecore DXP products.

The browser ID uniquely identifies a site visitor and associates captured events with that visitor. In this example, the browser ID identifies you and associates you with the actions you took: viewing the webpage and clicking the Promo component.

Next.js

In this topic, you'll start capturing events in a Next.js app that uses the App Router.

Setting up IDENTITY event capturing will run the identity function every time a site visitor clicks a button in your web app.

In production, you will most often capture IDENTITY events in forms.

Before you begin

In your code editor, open the root folder of your web app.
Install and initialize the Cloud SDK and the events package.

Browser side

To capture IDENTITY events on the browser side:

In your code editor, in the source code of your web app, create a page, for example, src/app/products/page.tsx.

Paste the following code into page.tsx, then save your changes:

"use client";
import { identity } from "@sitecore-cloudsdk/events/browser";

export default function Products(){
  return (
    <div>
      <button
        onClick={() =>
          identity({
            identifiers: [
              {
                id: "<YOUR_ID>", // example: "[email protected]"
                provider: "<YOUR_PROVIDER>" // example: "email"
              }
            ]
          })
        }>
        Send IDENTITY event
      </button>
    </div>
  );
}

This code imports the identity function from the browser module of the events package, and it displays a button on the webpage. Every time the button is clicked, the identity function runs, which sends an IDENTITY event.

Tip

In production, we recommend you pass your correct identity system data and pass other event data to the identity function to make sure that your web app captures rich event data.

In your terminal, enter npm run dev to start your Next.js app, then open the products page of your app in your web browser.
Click the button you just created to send the IDENTITY event to Sitecore.

Tip

Use your web browser's developer tools to check the payload that is sent to Sitecore.
To find the event in your Sitecore DXP products:
1. In your web browser's developer tools, view the cookies for your app.
2. Find a cookie named sc_cid.
3. Copy the cookie value. This value is the browser ID browser ID. You'll use it to find the event in your Sitecore DXP products.
  
  Example: a38b230c-11eb-4cf9-8d5d-274e9f344925

Server side

To capture IDENTITY events on the server side:

In your code editor, in the source code of your web app, locate the file where you initialized the Cloud SDK and the events package. The initialization code looks similar to:

import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";

// Import SDK modules ->
import { CloudSDK } from "@sitecore-cloudsdk/core/server";
import "@sitecore-cloudsdk/events/server";
import "@sitecore-cloudsdk/personalize/server";
import "@sitecore-cloudsdk/search/server";
// <- Import SDK modules

export default async function middleware(request: NextRequest) {
  const response = NextResponse.next();
  await CloudSDK(request, response, {
    sitecoreEdgeContextId: "<YOUR_SITECORE_EDGE_CONTEXT_ID>",
    siteName: "<YOUR_SITE_NAME>",
    enableServerCookie: true
  })
   .addEvents() // Initialize the events package
   .addPersonalize({ enablePersonalizeCookie: true, webPersonalization: { language: 'en' } }) // Initialize the personalize package
   .addSearch() // Initialize the search package
   .initialize(); // Run the initialization logic and set cookies
   
   return response;
};

At the top of the file, directly below the CloudSDK import statement, import the identity function from the server module of the events package:
// ... import { identity } from "@sitecore-cloudsdk/events/server";

Inside the middleware function, below the CloudSDK function, insert the identity function, then save your changes:

// Send event:
await identity(request, {
  identifiers: [
    {
      id: "<YOUR_ID>", // example: "[email protected]"
      provider: "<YOUR_PROVIDER>" // example: "email"
    }
  ]
});

This code sends an IDENTITY event.

Tip

In production, we recommend you pass your correct identity system data and pass other event data to the identity function to make sure that your web app captures rich event data.

In your terminal, enter npm run dev to start your Next.js app, then open the app in your web browser.
Click the button you created in the previous step to send the IDENTITY event to Sitecore.

Tip

Use your web browser's developer tools to check the payload that is sent to Sitecore.
To find the event in your Sitecore DXP products:
1. In your web browser's developer tools, view the cookies for your app.
2. Find a cookie named sc_cid.
3. Copy the cookie value. This value is the browser ID browser ID. You'll use it to find the event in your Sitecore DXP products.
  
  Example: a38b230c-11eb-4cf9-8d5d-274e9f344925

You're now tracking IDENTITY events in your web app as site visitors interact with your site. You can now find the events in your Sitecore DXP products. The collected event data will drive, for example, web analytics, segmentation, personalization, and more.

Next, you can:

To finish setting up identity resolution in SitecoreAI, create an identity rule.
Learn more about the IDENTITY event and what data you can include in it.
Learn more about tracking, what other events you can capture, and what the collected data can be used for.
Explore the reference documentation for the events package.
Set up other Sitecore DXP capabilities, such as using personalization to run web experiences or an interactive experience.

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