Full-page search widget events

Full-page search widgets show results to a user when they type a keyword in the search box and run that search. When a full-page search widget displays or a user interacts with that widget, you must send an event to Sitecore Discover.

Full-page search 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

You must send a widget appear event (widget:appear) 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 properties of the widget appear event object for full-page search widgets:

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 to a widget that is set up in the Customer Engagement Console (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 full-page search 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": "sp"
  }
}

Widget click events

You must send a widget click event (widget:click) when the user clicks on a full-page search widget. The widget click event is used for capturing clicks on products or embedded buttons. By capturing these clicks, Discover is able to calculate the following:

  • 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).

  • Keyword attributions such as search clicks, click revenue, Direct Purchase Revenue (DPR), Direct Order Revenue (DOR), Direct Orders (DO), and Direct Purchase Units (DPU).

  • 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.

The following table lists the properties of the widget click event object for a full-page search widget:

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.

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 if it is a product/facet link.

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

n/a

value.kw

string

Required.

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

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

n/a

value.m

string

Required if backend returns modified keyword.

Modified keyword that was returned as part of search response.

Calculates attribution to a modified keyword returned by API and used to compute keyword analytic metrics.

n/a

value.click_type

string

Required if this is a click on HTML content or an embedded action button.

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

n/a

value.click_text

string

Required if this is a click on HTML content or an embedded action button.

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

Example values: "Add to Cart", "Show", and "Quick View".

n/a

value.products

array

Required if click is product click.

Array with a single product object for a product that the user clicked.

n/a

value.products[].sku

string

Required if click is on a product.

SKU of the product the user clicked in a widget.

Used in calculating attribution metrics and keyword product analytics displayed on Keyword Details page.

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

Send a product click event when the user clicks on a product in a full-page search widget.

The following is an example of a widget click event that happens when a user clicks on a product in a full-page search widget:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",
    "f": "sp",
    "kw": "original keyword/search term",
    "m": "modified/corrected keyword/search term",   
    "click_type": "product"
    "index": 0,
    "products": [
      {
        "sku": "<product SKU>"
      }
    ]
  }
}

Add to cart click events

Send an Add to cart (a2c) click event when a user clicks Add to cart on a full-page search widget.

The following is an example of a widget click event that happens when a user clicks Add to cart on a full-page search widget:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",
    "f": "sp",
    "kw": "original keyword/search term",
    "m": "modified/corrected keyword/search term",   
    "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

Send an Add all to cart click event (all_a2c) when a user clicks Add all to cart on a full-page search widget.

The following is an example of a widget click event that happens when a user clicks Add all to cart on a full-page search widget:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",
    "f": "sp",
    "kw": "original keyword/search term",
    "m": "modified/corrected keyword/search term",   
    "click_type": "all_a2c",
    "click_text": "Add to cart",
    "index": 0,
    "products": [
      {
        "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 happens when a user clicks Quick view on a full-page search widget:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": <context object>,
    "rfkid": "<widget rfkid>",
    "f": "sp",
    "kw": "original keyword/search term",
    "m": "modified/corrected keyword/search term",   
    "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,