---
title: "Set up IDENTITY events"
slug: "set-up-identity-events"
abstract: "Use the Cloud SDK to start capturing IDENTITY events as your site visitors interact with your web app."
---
# Set up IDENTITY events

You can use the Cloud SDK [`events`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-events.html "@sitecore-cloudsdk/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 (guest[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N66588956cee31]) of your web app.

::::tabs
:::tab{title="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](https://github.com/sitecorelabs/xmcloud-foundation-head/blob/main/headapps/nextjs-starter/package.json)). 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.

> [!note]
> **Before you begin**
> -   Make sure your SitecoreAI site has [analytics identifiers](https://doc.sitecore.com/xmc/en/users/xm-cloud/en/manage-personalization-and-analytics-for-sites.html).
>
> -   Make sure [your SitecoreAI site's webpage has a component](https://doc.sitecore.com/xmc/en/users/xm-cloud/en/add-or-remove-an-element-in-a-page.html) to capture custom events from. [This webpage must be published](https://doc.sitecore.com/xmc/en/users/xm-cloud/en/publish-a-page.html) so the component appears on the website. This walkthrough uses the *Promo* component as an example.
>
> -   Make sure you're [ready to start development](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/prerequisites.html "Prerequisites") with the Cloud SDK.
>
> -   In your code editor, open your JSS Next.js app folder.

To capture `IDENTITY` events on the browser side:

1. In `Promo.tsx`, at the top of the file, import the `identity` function from the `browser` module of the `events` package:

    ```typescript
    import { identity } from "@sitecore-cloudsdk/events/browser";
    ```

2. In `Promo.tsx`, in the `Default` component, within the `return` statement, add a React `onClick` event handler to the topmost JSX element:

    ```typescript
    // ...
    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>`.

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

    ```typescript
    function handleClick() {
      identity({
        identifiers: [
          {
            id: "<YOUR_ID>",
            provider: "<YOUR_PROVIDER>"
          }
        ]
      });
      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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/custom-events.html "Custom events") and pass other event data to the `identity` function to make sure that your web app captures rich event data.

4. 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](https://nextjs.org/docs/pages/building-your-application/configuring/eslint#disabling-rules).

5. In your web browser, navigate to your JSS Next.js app, typically at `http://localhost:3000`.
6. 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.

7. Reload your webpage to start recording network activity.
8. On your webpage, click the *Promo* component.

    The click triggers the `IDENTITY` event.

9. 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.

10. In the request details pane, click the **Payload** tab for the request.
11. 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.

:::
:::tab{title="Next.js"}
In this topic, you'll start capturing events in a Next.js app that uses the [App Router](https://nextjs.org/docs/getting-started/installation#the-app-directory).

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.

> [!note]
> **Before you begin**
> -   In your code editor, open the root folder of your web app.
>
> -   [Install and initialize](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/install-and-initialize-the-cloud-sdk.html "Install and initialize the Cloud SDK") the Cloud SDK and the `events` package.

:::tab{title="Browser side"}
To capture `IDENTITY` events on the browser side:

1. In your code editor, in the source code of your web app, create a page, for example, `src/app/products/page.tsx`.
2. Paste the following code into `page.tsx`, then save your changes:

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

    export default function Products(){
      return (
        <div>
          <button
            onClick={() =>
              identity({
                identifiers: [
                  {
                    id: "<YOUR_ID>",
                    provider: "<YOUR_PROVIDER>"
                  }
                ]
              })
            }>
            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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/custom-events.html "Custom events") and pass other event data to the `identity` function to make sure that your web app captures rich event data.

3. 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.
4. 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/events.html#UUID-b78ff86e-4442-71e7-edc6-81adf8fabe27_section-idm234451877631545 "Checking the payload") that is sent to Sitecore.

5. 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_{SitecoreEdgeContextId}` , where `{SitecoreEdgeContextId}` is your [Context ID](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites").
    3. Copy the cookie value. This value is the browser ID[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N6659aee98cafa]. You'll use it to find the event in your Sitecore DXP products.

        Example: `a38b230c-11eb-4cf9-8d5d-274e9f344925​`

:::
:::tab{title="Server side"}
To capture `IDENTITY` events on the server side:

1. In your code editor, in the source code of your web app, locate the file where you [initialized](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/install-and-initialize-the-cloud-sdk.html "Install and initialize the Cloud SDK") the Cloud SDK and the `events` package. The initialization code looks similar to:

    ```typescript
    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;
    };
    ```

2. At the top of the file, directly below the `CloudSDK` import statement, import the `identity` function from the `server` module of the `events` package:

    ```typescript
    // ...
    import { identity } from "@sitecore-cloudsdk/events/server";
    ```

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

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

    This code sends an `IDENTITY` event.

    > [!tip]
    > In production, we recommend you [pass your correct identity system data](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/custom-events.html "Custom events") and pass other event data to the `identity` function to make sure that your web app captures rich event data.

4. In your terminal, enter `npm run dev` to start your Next.js app, then open the app in your web browser.
5. 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/tracking/events.html#UUID-b78ff86e-4442-71e7-edc6-81adf8fabe27_section-idm234451877631545 "Checking the payload") that is sent to Sitecore.

6. 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_{SitecoreEdgeContextId}` , where `{SitecoreEdgeContextId}` is your [Context ID](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/getting-started/prerequisites.html "Prerequisites").
    3. Copy the cookie value. This value is the browser ID[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N6659aee98cafa]. 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](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/working-with-the-collected-data.html "Working with the collected data"). The collected event data will drive, for example, web analytics, segmentation, personalization, and more.

Next, you can:

- Learn more about the [`IDENTITY`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/events/identity-events.html "IDENTITY events") event and what data you can include in it.
- Learn more about [tracking](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking.html "Tracking"), what other [events](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/events.html "Events") you can capture, and [what the collected data can be used for](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/working-with-the-collected-data.html "Working with the collected data").
- Explore the reference documentation for the [`events`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-events.html "@sitecore-cloudsdk/events") package.
- Set up other Sitecore DXP capabilities, such as using [personalization](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-personalization.html "Personalization") to run [web experiences](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/personalization/set-up-web-personalization.html "Set up web personalization") or an [interactive experience](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/developer-guides/personalization/set-up-interactive-personalization.html "Set up interactive personalization").

[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N66588956cee31]: A site visitor, also known as a user of your app. Site visitors are called guests in Sitecore CDP. That's why Cloud SDK developers encounter the term *guest* when they use the [`events`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-events.html "@sitecore-cloudsdk/events") package, and when they log in to Sitecore CDP to [find captured events](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/working-with-the-collected-data.html "Working with the collected data").

[^UUID-101b62f6-b640-ed11-1057-29646ebb9fb7_N6659aee98cafa]: A universally unique identifier (UUID) that Sitecore CDP assigns to every site visitor of your site. It is unique per browser, and it associates sessions and events with the respective site visitor. The Cloud SDK stores the browser ID as the value for the first-party `sc_{SitecoreEdgeContextId}` [cookie](https://doc.sitecore.com/sdk/en/developers/004/cloud-sdk/en/cloud-sdk-cookies.html) in the web browser.