1. Events

Custom events

Version:

A custom event can capture any action you choose to track. For example, clicks on components and how many times a site visitor adds items to their wish list.

You can send custom events by using the event function and passing it the custom event data object.

Note

The event function can also send a standard event, such as IDENTITY, ORDER_CHECKOUT or SC_SEARCH events if the correct payload is provided.

In general, we recommend that you send standard events using their dedicated functions instead of the event function. For example, send an IDENTITY event using the identity function.

The custom event data object

The custom 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, so make sure to provide the correct data depending on your organization's requirements. Construct the object in the following way:

  • Provide the name of the custom event. We recommend you choose a unique event name by including some unique value, such as the name of your site. For example, "myretailsite:CLICKED_PROMO".

    Important

    To send a custom event, do not set the name of a custom event to a reserved event name such as "VIEW" or "IDENTITY", or a name starting with SC_.

    The only scenario where can use reserved event names in the custom event data object is when you use the event function to send a standard event, such as IDENTITY, ORDER_CHECKOUT, or SC_SEARCH.

  • Optionally, you can:

    • Provide data such as the channel and the language of the page where the event triggered, and you can also add any custom attributes of your choice.

    • Include the extension data object.

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 15. Sending a custom event

Here's an example custom event data object for a custom event named "myretailsite:CLICKED_PROMO". The object contains all the required event data, and some optional event data and extension data. You can send this event by passing the object to the event function:

Browser module

const eventData: any = {
  type: "myretailsite:CLICKED_PROMO",
  language: "EN",
  page: "home",
  channel: "WEB",
  currency: "EUR",
  extensionData: { customKey: "customValue" }
};

event(eventData);

Server module

const eventData: any = {
  type: "myretailsite:CLICKED_PROMO",
  language: "EN",
  page: "home",
  channel: "WEB",
  currency: "EUR",
  extensionData: { customKey: "customValue" }
};

await event(request, eventData);

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

{
  "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
  "channel": "WEB",
  "client_key": "",
  "currency": "EUR",
  "ext": {
    "customKey": "customValue"
  },
  "language": "EN",
  "page": "home",
  "pos": "",
  "requested_at": "2026-10-05T10:36:32.506Z",
  "type": "myretailsite:CLICKED_PROMO"
}


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