Adding context to an event object

Context objects are required for all events sent to the Sitecore Search Events API. Sitecore Search uses context objects to describe additional information about the visitor visiting the site, the visitor's location, the page they are visiting, and the device they are using.

The following lists the required objects that must be sent in the context object:


These objects must be included in every context object for events to be logged correctly.

  • browser - the browser object must be included along with either the browser user agent (browser.user_agent) or the type of device the visitor is accessing your site with (browser.device).


    If browser.user_agent is included and correctly follows industry convention, browser.device and browser.app_type are detected automatically.

  • geo - the geo object must be included along with either the visitor's IP address (geo.ip) or the visitor's country ( and state (geo.state).


    If geo.ip is provided, Sitecore Search uses the IP address to automatically determine the visitor's country, state, city, and zip code.

The following is an example of a context object in an event:


For the event object data model, see the Events API reference.

  "action": "<event action>",
  "name": "<event name>",
  "value": {
    "entities": [
        "attributes": {
          "author": "<Author of entity>"
        "entity_subtype": "article/blog",
        "entity_type": "content, product",
        "id": "<External unique identifier for the entity>",
        "uri": "<URI of the entity>"
    "context": {
      "browser": {
        "user_agent": "Mozilla/5.0 (iPhone14,6; U; CPU iPhone OS 15_4 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19E241 Safari/602.1"
      "geo": {
        "ip": "10.x.x.x"
      "page": {
        "locale_language": "en",
        "locale_country": "us",
        "locale_currency": "usd"
      "user": {
        "cuid": "user-1234",
        "email": "[email protected]",
        "eid": "<hash_of_email>",
        "fbid": "<facebook_id>",
        "address": {
          "address_line_1": "123 Main Street",
          "address_line_2": "apartment 123",
          "state": "CA",
          "zip": "90210",
          "country": "USA"

Do you have some feedback for us?

If you have suggestions for improving this article,