1. Event specifications

Recommendation widget events

Recommendation widgets display recommended products to your customers. These products are chosen based on user affinities such as brands, colors, and so on. When a user sees or interacts with one of these widgets, you must send that event to Sitecore Discover.

Recommendation events include widget appear and widget click events. Discover uses these events to calculate the performance metrics of widgets on your site.

Widget appear events

The widget appear event (widget:appear) must be sent when the user views a recommendation widget on a page. Often the user does not scroll all the way down to see the widget. For analytics to report the correct attribution numbers, this event must only be sent when the widget is within the user's viewport.

This event is used to calculate:

  • Sitecore Discover view-assisted attributions, such as view-assisted revenue, orders, and conversions. These attributions are calculated at the domain, widget type, and widget levels.
  • Click-through rate (CTR) for the site, widget type, or widget.

The following table lists the keys of the widget appear event object for recommendation widgets:

KeyTypeDescriptionValue
typestringRequired.Type of the event.widget
namestringRequired.Name of the event.appear
value.rfkidstringRequired.Used to associate this event to a widget that is set up in CEC.ImportantThis must match the corresponding rfkid set up in CEC. If the rfkid is not provided or the wrong rfkid is sent, then no attribution numbers for that widget are reported.n/a
value.f(deprecated)stringOptional.Type of widget.sp (search page)
value.context.pageobjectRequired if the site is set up with locale configuration.Adds page-specific information (including locale information) under the page object.n/a
value.locale (deprecated)objectOptional.A locale object. Deprecated. We recommend that you use value.context.page for locale information.n/a

The following is an example of a widget appear event object for a recommendation widget. This example is in the new format, which means it contains a context object.

{
  "type": "widget",
  "name": "appear",
  "value": {
    "context": {<context object>},
    "rfkid": "<widget rfkid>",
    "f": "rw"
  }
}

Widget click events

You must send a widget click event (widget:click) when the user clicks a recommendation widget. The widget click event is used for capturing clicks on products, Add to Cart, Quick View, and so on. By capturing these clicks, Discover is able to calculate the following:

  • Sitecore Discover click-assisted attributions, such as click-assisted revenue, orders, and conversions. These attributions are calculated at the domain, widget type, and widget levels.
  • Click-through rate (CTR) for site, widget type, and widget.
  • Direct attributions, such as Direct Order Revenue (DOR), Direct Purchase Revenue (DPR), Direct Orders (DO), and Direct Purchase Units (DPU).

The following table lists the properties of the widget click event object for a recommendation widget:

KeyTypeDescriptionValue
typestringRequired.Type used to identify the event.widget
namestringRequired.Name used to identify the event.click
value.rfkidstringRequired.Used to associate this event with a widget that is set up in the CEC.ImportantThis must match the corresponding rfkid set up in CEC. If the rfkid is not provided or the wrong rfkid is sent, then no attribution numbers for that widget are reported.n/a
value.f (deprecated)stringOptional.Type of widget.rw (recommendation widget)
value.indexnumberRequired.Position of the product/link that the user clicked in a widget. Indexing starts at 0.n/a
value.productsarrayRequired.Products array having a single product object that the user clicked in a widget.n/a
value.products[].skustringRequired.SKU of the product the user clicked in a widget.n/a
value.click_typestringRequired if the click is on an HTML content block or embedded link.The type of link or button that is associated with this click event.n/a
value.click_textstringOptional.The label associated with the click_type.n/a
value.context.pageobjectRequired if the site is set up with locale.Adds page-specific information (including locale information) under page object.n/a
value.locale (deprecated)objectOptional.A locale object. Deprecated. We recommend that you use value.context.page for locale information.n/a

Product click events

The product click event must be sent when the user clicks on a product in a recommendation widget. Most clicks on a recommendation widget are product clicks.

The following is an example of a widget click event on a product in a recommendation widget:

{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",
    "click_type": "product",
    "f": "rw",
    "index": 0,
    "products": [     
      {
        "sku": "191258"
      }
    ]
  }
}

Add to cart click events

The Add to cart click event (a2c) must be sent when a user clicks an embedded Add to cart button on a recommendation widget.

The following is an example of a widget click event that takes place on an Add to cart button on a recommendation widget:

{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": <Widget rfkid>,
    "click_type": "a2c",
    "click_text": "Add to cart",
    "index": 0,
    "products": [
      {
        "sku": "<product SKU>"
      }
    ]
  }
}
Important

In addition to this widget click event, you must also send an Add to cart funnel event for the product added to the cart.

Add all to cart click events

The Add all to cart click event (all_a2c) must be sent when a user clicks an embedded Add all to cart button on a recommendation widget.

The following is an example of a widget click event that takes place on an Add all to cart button on a recommendation widget:

{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",
    "click_type": "all_a2c",
    "click_text": "Add All to Cart",
    "products": [
      {
        "sku": "<product SKU>"
      },
      {
        "sku": "<product SKU>"
      }
    ]
  }
}
Important

In addition to this widget click event, you must also send Add to cart funnel events for the products added to the cart.

View click events

Send a View click event (view) when a user clicks a button that opens a modal showing additional details about a product. This button might be labeled Quick view, View details, Shop now, and so on.

The following is an example of a widget click event that takes place on a Quick view button on a recommendation widget:

{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",   
    "click_type": "view",
    "click_text": "Quick view",
    "index": 0,
    "products": [
      {
        "sku": "<product SKU>"
      }
    ]
  }
}
If you have suggestions for improving this article, let us know!