Widget view events

Events

Tracking
Events
Widget view events

Version:

The widget view event tracks when the site visitor views a Sitecore Search widget in your app.

You can send widget view events by using the widgetView function and passing it the widget view event data object.

The widget view event data object represents all the required and optional data about the event.

This is the object where you provide data about the event. All this data is sent to Sitecore Search, so make sure to provide the correct data depending on your organization's requirements. Construct the object in the following way:

Provide the ID of the widget ID of the widget that was viewed, data about the index documents that were viewed, and the URI where the event triggered.
Optionally, you can provide data such as the channel and the language of the page where the event triggered.

Examples

Tip

During development, use your web browser's developer tools to check the payload containing all the event data that is sent to Sitecore.

Example 9. Sending a widget view event

Here's an example event data object for a widget view event. The object contains all the required and some optional event data. You can send this event by passing the object to the widgetView function:

Browser module

import { widgetView } from "@sitecore-cloudsdk/search/browser";
import type { WidgetViewEventParams } from "@sitecore-cloudsdk/search/browser";

const eventData: WidgetViewEventParams = {
  request: {
    keyword: "green",
    numResults: 3,
    totalResults: 3,
    numRequested: 10
  },
  entities: [
    {
      entity: "product",
      id: "1"
    },
    {
      entity: "product",
      id: "2"
    },
    {
      entity: "product",
      id: "3"
    }
  ],
  pathname: "/page",
  widgetId: "rfkid_7"
};

widgetView(eventData);

Server module

import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";
import { CloudSDK } from "@sitecore-cloudsdk/core/server";
import { widgetView } from "@sitecore-cloudsdk/search/server";
import type { WidgetViewEventParams } from "@sitecore-cloudsdk/search/server";

export default async function middleware(request: NextRequest) {
  const response = NextResponse.next();

  // Initialize the SDK and the package...

  // Send event:
  const eventData: WidgetViewEventParams = {
    request: {
      keyword: "green",
      numResults: 3,
      totalResults: 3,
      numRequested: 10
    },
    entities: [
      {
        entity: "product",
        id: "1"
      },
      {
        entity: "product",
        id: "2"
      },
      {
        entity: "product",
        id: "3"
      }
    ],
    pathname: "/page",
    widgetId: "rfkid_7"
  };

  const widgetViewResponse = await widgetView(request, eventData);
  console.log("Sent widget view event.", widgetViewResponse);

  return response;
}

For this widget view event data object, the following payload is sent to Sitecore:

{
  "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925",
  "client_key": "",
  "language": "EN",
  "page": "search",
  "pos": "",
  "requested_at": "2026-01-13T09:18:06.130Z",
  "sc_search": {
    "data": {
      "action_cause": "entity",
      "value": {
        "context": {
          "page": {
            "uri": "/page"
          }
        },
        "entities": [
          {
            "entity_type": "product",
            "id": "1"
          },
          {
            "entity_type": "product",
            "id": "2"
          },
          {
            "entity_type": "product",
            "id": "3"
          }
        ],
        "request": {
          "keyword": "green",
          "num_requested": 10,
          "num_results": 3,
          "total_results": 3
        },
        "rfk_id": "rfkid_7"
      }
    },
    "metadata": {
      "ut_api_version": "1.0"
    }
  },
  "type": "SC_SEARCH_WIDGET_VIEW"
}

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