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:

Key

Type

Description

Value

type

string

Required.

Type of the event.

widget

name

string

Required.

Name of the event.

appear

value.rfkid

string

Required.

Used to associate this event to a widget that is set up in CEC.

Important

This 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)

string

Optional.

Type of widget.

sp (search page)

value.context.page

object

Required 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)

object

Optional.

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.

RequestResponse
{
  "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:

Key

Type

Description

Value

type

string

Required.

Type used to identify the event.

widget

name

string

Required.

Name used to identify the event.

click

value.rfkid

string

Required.

Used to associate this event with a widget that is set up in the CEC.

Important

This 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)

string

Optional.

Type of widget.

rw (recommendation widget)

value.index

number

Required.

Position of the product/link that the user clicked in a widget. Indexing starts at 0.

n/a

value.products

array

Required.

Products array having a single product object that the user clicked in a widget.

n/a

value.products[].sku

string

Required.

SKU of the product the user clicked in a widget.

n/a

value.click_type

string

Required 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_text

string

Optional.

The label associated with the click_type.

n/a

value.context.page

object

Required if the site is set up with locale.

Adds page-specific information (including locale information) under page object.

n/a

value.locale (deprecated)

object

Optional.

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:

RequestResponse
{
  "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:

RequestResponse
{
  "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:

RequestResponse
{
  "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:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",   
    "click_type": "view",
    "click_text": "Quick view",
    "index": 0,
    "products": [
      {
        "sku": "<product SKU>"
      }
    ]
  }
}

Do you have some feedback for us?

If you have suggestions for improving this article,