Skip to main content

Generic widget events

Abstract

Describes the Sitecore Discover generic widget event.

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

This topic describes generic widget appear and widget click events. Refer to Recommendation widget events, Full page search widget events, or Preview search widget events for event specification for those widgets.

The widget appear (widget:appear) event must be sent when the user sees a Sitecore Discover widget on your site. Use this event to capture appears for all widgets, including HTML content blocks, Discover widgets, or other types of widgets.

Note

The widget:appear event is also referred to as track:appear in the old convention.

The information provided in this event object is used to calculate the following:

  • 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 site, widget type, or widget.

The following table lists properties for the generic widget appear event object:

Name

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 with a widget that is set up in the Customer Engagement Console (CEC).

Important

This must match the corresponding rfkid set up in the 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.context.page

object

Required if the site is set up with locale configuration.

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

n/a

The following is an example of a generic widget appear event object. 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": "<widget type>"
  }
}

The widget click event (widget:click) must be sent when the user clicks anywhere on a Sitecore Discover widget. Use this event to capture button clicks on HTML content block widgets and embedded buttons such as Add to cart or Quick view, and so on.

The information provided in this event object is used 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 the site, widget type, or widget.

  • Direct attributions, such as Direct Order Revenu.e (DOR), Direct Purchase Revenue (DPR), Direct Orders (DO), and Direct Purchase Units (DPU).

The following table lists the properties of the generic widget click event object:

Name

Type

Description

Value

type

string

Required.

Type of the event.

widget

name

string

Required.

Name of 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.

sp (search page)

value.index

number

Required for product and facet links.

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

n/a

value.kw

string

Required.

Original keyword or search text that the user entered in the search box.

Calculates attribution to the keyword entered by the user. Used to compute keyword analytic metrics

n/a

value.m

string

Required only if back end returned modified keyword

Modified keyword that was returned as part of the search response.

Calculates attribution to a modified keyword returned by Search API. Used to compute keyword analytic metrics.

n/a

value.click_type

string

Required for clicks on HTML content or embedded action buttons

The type of link or button that is associated with this click event.

n/a

value.click_sub_type

string

Optional.

Additional subtype of the link or button that the user clicked.

n/a

value.click_text

string

Required for clicks on HTML content or embedded buttons.

Label value of the link/button associated with the preceding click type.

Example values are "Add to Cart", "Show", "Quick View", and so on.

n/a

value.click_text_id

string

Optional.

Normalized text ID of a label value associated with the link or button that the user clicked.

n/a

value.click_uri

string

Required if the clicked link has a URI associated with it.

URI associated with the click.

n/a

value.products

array

Required for product clicks.

Array with a single product object that the user clicked in a widget.

n/a

value.products[].sku

string

Required for product clicks.

SKU of the product the user clicked in a widget.

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