Recommendations and Pathways Integration

Integration Prerequisites


Before integrating the Recommendations and Pathways feature, you need:

  • Active Recommendations and Pathways feature: Bloomreach will activate and provide an implementation plan after you purchase the Recommendations and Pathways feature. If you want to learn about the feature add-on license, please contact your Bloomreach Account Manager.

    NOTE: If you're integrating Third-Party Widget Pixels, you do not need an active Recommendations and Pathways feature. Read more about Third-Party Widget Pixels here.

  • Widget placement plan: We recommend that you plan and list the page types where you want to place your widgets. On these pages, you will need to implement the Recommendations and Pathways Pixel, UI, and API call.

Integration Steps


Steps to integrate are given below:

To integrate the Recommendations and Pathways feature, ensure all integration components (feed, pixel, and API) are ready to deploy.

Step 1: Upload Feed


Feed is the content of your product catalog on which the Recommendations and Pathways feature works. You can upload your product feed on the Bloomreach FTP site or use your own FTP site for the same. Ensure that you generate product feed daily to keep your product data up-to-date. Learn about generating and uploading Product Feed on the Full Product Feed page.

NOTES:

  1. Consult your Bloomreach representative about the custom changes that might be required on your product feed for the Recommendations and Pathways feature.
  2. Curated widget and Category Pathways widgets are manually curated and do not require any feed changes.

Setting Up Data (Pathways examples)

Custom Pathways widgets use data from your product feeds, including delta feeds, to determine which products to display. You may have to add new fields to your feed, depending on what you want to display in the widget. See the table below for example fields:

Widget typeFeed Field RequiredField values
Brand Highlight“Brand”The brand name
Excess Inventory“Excess Inventory”Yes/No
New Arrivals“New Arrival”Yes/No
New Since Last Visit“Launch Date”Date in the format YYYYMMDD
On Sale“On Sale”Yes/No
Recipe pages“Recipe”The ID of the recipe. It should be unique such that it does not match any potential query or other feed values. Example: H381GA9.

Step 2: Integrate Pixels


Overview

In this step, you will implement pixels to capture different events: Views, Clicks, and Add-to-cart. There are two main integration methods: code-based and code-free (using a Tag Manager). After pixel implementation, you’ll validate the pixels to ensure accurate tracking.

Why integrate pixels

Pixel tracks the activities of shoppers on your live site. This tracking​​ impacts your site in two key ways:

  • Better search relevance: Pixel integration impacts the relevance of search results on your site and prevents underperforming products from appearing at the top.
  • Learn from shoppers’ behavior: Bloomreach uses Pixel to learn from shoppers' behavior to optimize features dynamically.

What to integrate

You must integrate the below pixels in the provided order:

  1. Core Bloomreach pixels
    You must implement the core Bloomreach pixels first for the Recommendation and Pathways pixel to work. Install the core Bloomreach pixels by following the Pixel Deployment Page guide. Allow four weeks after the pixel is live in production to build up analytics.
  2. Recommendations and Pathways feature pixels/Third-party widget pixels [whichever applicable]
    You may be using a Bloomreach-powered widget or a third-party widget. Implement the Bloomreach widget pixel or third-party widget pixel to track the View, Click, and Add-to-cart events. Different events require different snippets and should be added individually.

How to integrate

Choose from one of these two methods to integrate:

  • Code-based integration: To integrate the pixels, you must add a Javascript snippet to your code to all the pages, on all the versions - desktop, mobile, and tablet. You can add the tracking code snippet to your global footer to ensure it is added everywhere.
  • Code-free integration: If you use a Tag Manager to track events, you can set up the Bloomreach pixel without adding any code. To learn how to do this, go to Tag Manager Pixel Integration.

Event Tracking Snippets

Below sections cover tracking snippets for each event type. Each Javascript tracking pixel is defined by the BrTrk.getTracker().logEvent.

View Event Tracking Pixel

This pixel tracks the impressions of the customer whenever they view a recommendation widget. For every widget that is added to the page, a corresponding widget view pixel has to be fired.

To track the view event, install the following Javascript tracking pixel snippet below on all your pages.

View Event Tracking Snippet for Bloomreach-powered widgets

var widget_view_data = {}
   widget_view_data.wrid = 'abcd123'
   widget_view_data.wq = 'black dress'
   widget_view_data.wid = 'abc123'
   widget_view_data.wty = 'mlt'
BrTrk.getTracker().logEvent('widget', 'widget-view', widget_view_data, true)

View Event Tracking Snippet for non-Bloomreach-powered widgets

var widget_view_data = {}
   widget_view_data.wrid = 'br_ext'
   widget_view_data.wq = 'black dress'
   widget_view_data.wid = 'br_ext'
   widget_view_data.wty = 'br_ext'
BrTrk.getTracker().logEvent('widget', 'widget-view', widget_view_data, true)

The following table describes the variables in the tracking snippet. Please note that the variable values differ for Bloomreach-powered and non-Bloomreach-powered widgets.

VariableData TypeDescriptionRequiredExample values [Bloomreach Powered widgets]Example values [Non-Bloomreach Powered widgets]
widget_view_data.wridStringThe unique ID of the response.Requiredabcd123br_ext
widget_view_data.wqStringThe query string used by the customer which returns a widget suggestion.ConditionalThis is optional for non-query widgets.black dressblack dress
widget_view_data.widStringThe widget ID. This is a unique, 6-character alphanumeric value.Requiredabc123br_ext
widget_view_data.wtyStringThe type of recommendation widget. The value returned in the API response shall be passed as a widget type.Requiredmlt,jfy, etc.br_ext

Click Event Tracking Pixel

When a customer clicks on a Recommendation widget, a click event occurs and is tracked by a Javascript tracking pixel. To track the click event, install the following Javascript tracking pixel snippet below on all of your pages:

Click Event Tracking Snippet for Bloomreach-powered widgets

var widget_data = {}
    widget_data.wrid = 'abcd123'
    widget_data.wq = 'black dress'
    widget_data.wid = 'abc123'
    widget_data.wty = 'mlt'
    widget_data.item_id = 'pd123'
BrTrk.getTracker().logEvent('widget','widget-click', widget_data,true)

Click Event Tracking Snippet for Non-Bloomreach Powered widgets

var widget_data = {}
    widget_data.wrid = 'br_ext'
    widget_data.wid = 'br_ext'
    widget_data.wty = 'br_ext'
    widget_data.item_id = 'pd123'
BrTrk.getTracker().logEvent('widget','widget-click', widget_data,true)

The following table describes the variables in the tracking snippet. Please note that the variable values differ for Bloomreach-powered and non-Bloomreach-powered widgets.

VariableData TypeDescriptionRequiredExample values [Bloomreach Powered widgets]Example values [Non-Bloomreach Powered widgets]
widget_data.wridStringThe unique ID of the response.Requiredabcd123br_ext
widget_data.wqStringThe query string used by the customer which returns a widget suggestion.Conditional: This is optional for non-query widgets.black dress-
widget_data.widStringThe widget ID. This is a unique, 6-character alphanumeric value.Requiredabc123br_ext
widget_data.wtyStringThe type of recommendation widget. The value returned in the API response shall be passed as a widget type.Requiredmlt,jfy, etc.br_ext
widget_data.item_idStringThe unique ID of the clicked product/ category/content/ item.Requiredpd123pd123

Direct Add-to-Cart Event Tracking Pixel

This pixel tracks the customer’s activity when the ATC button within the widget is clicked. This pixel should be installed if you have placed an Add-to-Cart button within a widget.

To track the add-to-cart event, install the following Javascript tracking pixel snippet below on all of your pages:

Add-to-Cart Event Tracking Snippet for Bloomreach-powered widgets

var widget_atc_data = {}  
           widget_atc_data.wrid = 'abcd123' 
           widget_atc_data.wq = 'black dress' 
           widget_atc_data.wid = 'abc123' 
           widget_atc_data.wty = 'mlt' 
           widget_atc_data.item_id = 'id123' 
           widget_atc_data.sku = 'sk123' 
BrTrk.getTracker().logEvent('cart','widget-add', widget_atc_data)

Add-to-Cart Event Tracking Snippet for non-Bloomreach-powered widgets

var widget_atc_data = {}  
           widget_atc_data.wrid = 'br_ext' 
           widget_atc_data.wid = 'br_ext' 
           widget_atc_data.wty = 'br_ext' 
           widget_atc_data.item_id = 'id123' 
           widget_atc_data.sku = 'sk123' 
BrTrk.getTracker().logEvent('cart','widget-add', widget_atc_data)

The following table describes the variables in the tracking snippet. Please note that the variable values differ for Bloomreach-powered and non-Bloomreach-powered widgets.

VariableData TypeDescriptionRequiredExample values [Bloomreach Powered widgets]Example values [Non-Bloomreach Powered widgets]
widget_atc_data.wridStringThe unique ID of the response.Requiredabcd123br_ext
widget_atc_data.wqStringThe query string used by the customer which returns a widget suggestion.Conditional: This is optional for non-query widgets.black dress-
widget_atc_data.widStringThe widget ID. This is a unique, 6-character alphanumeric value.Requiredabc123br_ext
widget_atc_data.wtyStringThe type of recommendation widget.Requiredmlt,jfy, etc.br_ext
widget_atc_data.item_idStringThe unique ID of the clicked product/ category/content/ item.Requiredid123id123
widget_atc_data.skuStringUnique SKU ID that represents the selected variant of this product (e.g., size M, color blue of a t-shirt).Conditional: If your site does not have SKUs, leave this blank.sku123sku123

Validate pixel implementation

If you're integrating Recommendations widgets, you must validate your pixel implementation. Visit the Test Scenarios - Recommendations guide to learn more.

Step 3: Create Widget on Dashboard


The next step is to create a widget on the Bloomreach Dashboard. The step-by-step process of creating and managing a widget is illustrated in the Widget Configurator guide.

📘

Test widget on Staging

When you first create a widget, perform this step in your staging Dashboard to test it in your staging environment. You can recreate this widget in your production environment later.

Step 4: Integrate the API


The Recommendation APIs — like the other Bloomreach APIs — are RESTful and provide data for the features on your mobile and desktop pages. These APIs are performed over HTTP 1.1 protocol, and the response is JSON-formatted. View the detailed documentation on the Recommendations and Pathways API page.

At the end of the integration, your system should be ready to pick user behavior on your site (via Pixels) and send it to Bloomreach (via APIs) and be able to receive relevant recommendations from user behavior and the data set (provided from the feed).