Set up custom events

In this topic, you'll start capturing events on the browser side in a JSS Next.js app (JSS version 22.2).

Setting up custom event capturing will run the event function every time a site visitor clicks a component in your web app.

To capture custom events on the browser side:

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

   import { event } 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:

   // ...
   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:

   function handleClick() {
     event({ type: "myretailsite:CLICKED_PROMO" })
       .catch((e) => console.debug(e));
     console.log("Sent custom event.");
   };

   This code runs the event function every time the Promo component is clicked, and sends a custom event named myretailsite:CLICKED_PROMO to Sitecore.

   Tip

   In production, we recommend you pass event data to the event function to make sure that your web app captures rich event data, and that you choose a unique event name that accurately describes the event you are tracking.

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.

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

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

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

To capture custom events on the server side:

1. 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;
   };

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

   // ...
   import { event } from "@sitecore-cloudsdk/events/server";

3. Inside the middleware function, below the CloudSDK function, run the event function, then save your changes:

   // Send event:
   await event(request, { type: "myretailsite:CLICKED_BUTTON" });

   This script sends a custom event named myretailsite:CLICKED_BUTTON.

   Tip

   In production, we recommend you pass event data to the event function to make sure that your web app captures rich event data, and that you choose a unique event name that accurately describes the event you are tracking.

4. In your terminal, enter npm run dev to start your Next.js app, then open your app in your web browser.

5. Click the button you just created to send the custom event to Sitecore.

   Tip

   Use your web browser's developer tools to check 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_cid.

   3. Copy the cookie value. This value is the browser ID. You'll use it to find the event in your Sitecore DXP products.

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