Preview search widget events

Preview search widgets display suggestions to users when they interact with a search bar or icon on your page.

These widgets work regardless of whether a keyword is present. The user might click on a suggested category or product without ever entering a keyword. They might also type a keyword and then click on a suggested keyword, click on a product result, or press enter, which brings them to a full-page search.

Preview search events include widget appear and widget click events. Sitecore 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 sees a Sitecore Discover preview search widget on your site.

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, and widget.

The following table lists properties for the preview search widget appear event:

Name

Type

Description

Value

type

string

Required.

Type of the event. Value is a constant string: "widget"

widget

name

string

Required.

Name of the event. Value is a constant string: "appear"

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 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.f(deprecated)

string

Optional.

Type of widget.

sb (search bar)

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

Widget click events

You must send a widget click event (widget:click) when a user clicks on a preview search widget. This event is used for capturing clicks on several different types of embedded buttons.

The following table lists the properties of the widget click event object for a preview 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 to a widget that is set up in the 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.f (deprecated)

string

Optional.

Type of widget.

sb (search bar)

value.w

string

Required.

Where in the widget the user clicked. See following sections for values.

n/a

value.index

integer

Optional.

Position or index of the product that was clicked. Indexing starts from 0.

n/a

value.kw

string

Required if the user typed something in the search box.

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

n/a

value.m

string

Required if back end returned modified keyword.

Modified keyword that was returned as part of search response.

Calculates attribution to modified keyword returned by Search API.

n/a

value.text

string

Required.

Text of the link that the user hovers over or clicks.

n/a

value.type

string

Required.

Type of suggestion link that the user clicks or hovers over.

  • trending_category

  • trending_brand

  • keyphrase

  • category

  • brand

sku

string

Either sku or products is required for product clicks.

Product variation SKU

n/a

products

array

Either sku or products is required for product clicks.

Array containing a single product object.

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 page object.

n/a

value.locale (deprecated)

object

Optional.

A locale object. This attribute is deprecated. We suggest you use the page object for locale data.

n/a

Product click events

Send this event when a user clicks a product in a preview search widget.

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

  • Keyword and keywordless attribution to the product section of the widget.

  • Direct click attribution metrics in keyword analytics.

  • Top clicked products in widget and keyword analytics.

Tip

When sending a product click event, value.type must be the type of link the user hovers over before they click the product.

The following image represents a user interaction with the preview widget. In this interaction, the user starts typing the search term watch and a list of suggested search terms appears under the heading Did You Mean? The user hovers the mouse over the word Watch in the list and a collection of watches appears. The user then clicks on the first watch in the collection.

Screenshot of preview search widget with watch highlighted.

When the user clicks the watch, you must send the following event to Discover:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": {
      "page": {
        "locale_country": "<2 letter country code>",
        "locale_language": "<2 letter language code>",
        "locale_currency": "<3 letter currency code>"
      }
    },
    "rfkid": "<widget rfkid>",
    "kw": "wat",
    "m": "watch",
    "text": "Watch",
    "type": "keyphrase",
    "w": "suggestion",
    "index": 0,
    "sku": 191258
  }
}

Suggested category or brand click events

Send this event when a user clicks on a suggested category or brand in the preview search widget.

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

  • Sitecore Discover click-assisted attributions in widget and keyword analytics.

Tip

For suggested category or brand click events, set value.w to "suggestion".

The following image represents a user interaction with the preview widget. In this interaction, a user clicks in the search bar and starts typing the search term axle. Before they finish typing, Axle appears as a suggested category, and the user clicks it.

Open preview search widget with Axle category highlighted.

When the user clicks the suggested category, you must send the following event to Discover:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": {
      "page": {
        "locale_country": "<2 letter country code>",
        "locale_language": "<2 letter language code>",
        "locale_currency": "<3 letter currency code>"
      }
    },
    "rfkid": "<widget rfkid>",
    "w": "suggestion",
    "kw": "ax",
    "m": "axle",
    "text": "Axle",
    "type": "category",
    "index": "2"
  }
}

Suggested keyphrase click events

Send this event when a user clicks on a suggested keyphrase in a preview search widget.

Tip

For suggested keyphrase click events, set value.w to "suggestion"

The following image represents a user interaction with the preview widget. In this interaction, a user clicks in the search bar on your page and starts typing the search term watch. As they type, suggested keyphrases appear under the Did You Mean? heading. The user clicks the first keyphrase in this list, Watch.

Screenshot of preview search widget with word "Watch" highlighted.

When the user clicks on the suggested keyphrase, you must send the following event to Discover:

RequestResponse
{
  "type": "widget",
  "name": "click",
  "value": {
    "context": {
      "page": {
        "locale_country": "<2 letter country code>",
        "locale_language": "<2 letter language code>",
        "locale_currency": "<3 letter currency code>"
      }
    },
    "rfkid": "<widget rfkid>",
    "w": "suggestion",
    "kw": "wat",
    "m": "watch",
    "text": "watch",
    "type": "keyphrase",
    "index": "0"
  }
}

Top category or brand click events

Send this event when a user clicks on a top category or brand on the preview search widget.

Tip

For top category or brand click events, set value.w to "suggestion".

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

  • Keyword and keywordless attribution to the Top category or Top brand section of the widget.

  • Top categories or brands clicked in the widget.

  • Sitecore Discover click-assisted attribution in widget and keyword analytics.

The following image represents a user interaction with the preview widget. In this interaction, a user clicks in the search bar, and the preview search widget opens on their screen. Without typing anything in the search bar, they click on the first link in the popular categories list (Transmissions).

Screenshot of preview search widget with list of Popular Categories. The first item in the list (Transmission) is highlighted.

When the user clicks the Transmissions category, you must send the following event to Discover:

RequestResponse
{  
  "type": "widget",
  "name": "click",
  "value": {
    "context": {
      "page": {
        "locale_country": "<2 letter country code>",
        "locale_language": "<2 letter language code>",
        "locale_currency": "<3 letter currency code>"
      }
    },
    "f": "sb",
    "rfkid": "<widget rfkid>",
    "w": "suggestion",
    "text": "Transmissions",
    "type": "trending_category",
    "index": "0"
  }
}

Do you have some feedback for us?

If you have suggestions for improving this article,