Integration Overview - Bloomreach Experience - Open Source CMS

Integration Overview

To integrate Pathways and Recommendations, you must ensure all the integration components: the feed, pixel, and API are ready to be deployed. 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). 

Before getting started, plan out a list of page types and locations where you want to place your widget. On these pages, you will need to implement the Pathways Pixel, UI and API call. 

Steps to integrate are:

Step 1: Upload Feed

Step 2: Integrate Pixel

Step 3: Create a Widget 

Step 4: Integrate Recommendations API 

Activate Widget Feature
For Pathways and Recommendations, your account must be activated for the add-on feature. Bloomreach will activate the feature and provide you with an implementation plan one you purchase the feature. If you want to learn about the Pathways & Recommendations add-on license please contact your Bloomreach Account Manager.
Before You Begin

Before you begin your integration, take a quick look at the steps that are required for Recommendations based on whether you are an existing customer or new to our platform.

If you are a new customer, you have to:

- Upload Product Feed
: This is the primary requirement for any Bloomreach Search and Merchandising feature. As a new customer, you will need to send us data from your product catalog (such as product name, price, product ID, etc) as a CSV, TSV or XML file in a format that can be consumed by us. Consult your TPM on specific product feed requirements for Recommendations. To know more about how to upload your product feed, see the Product Feed section.

- Integrate Recommendation Pixels: Pixels are components that collect user behavior data from your live site and pass it on to Bloomreach. This data is the primary source of powering our algorithms to give you the most relevant Search and Merchandising experience. As a new customer, you have to integrate:
         - Bloomreach standard pixels
         - Pathways and Recommendations pixels

- Create Pathways/Recommendation Widget (Dashboard): As one of the important steps of integrating Recommendations, is to create a recommendation widget from the Dashboard. This auto-generates a widget_id that you have to send in the API calls for Recommendation. 

- Integrate Recommendation API: The Recommendation API returns product data from your data set powered by our algorithm. The APIs are powerful REST calls that return highly curated, relevant recommendation results for your customers.

If you are an existing customer, you have to:

- Update Feed
: To implement Pathways and Recommendations, a few feed changes will be needed. Consult your TPM about custom changes that might be required on your Product Feed. The details about setting up feed data for Pathways widgets in available in the Setting up Data section on this page. 

- Configure Pixels: As an existing customer, you already have the standard pixels integrated on your site and that's what makes all the Bloomreach Search and Merchandising features work for you. At this point you need to verify and validate your existing pixels especially product view, ATC and conversion pixels. To use Recommendations, you will additionally have to integrate the recommendation pixels to allow collecting user behavior data from your site and sending it to Bloomreach. The steps to configuring pixels are available in the Integrating Pixels section on this page. 

- Create Recommendations Widget (Dashboard): One of the key things you will need for Recommendation integration is the widget_id. The widget_id is auto-generated when you create a recommendation widget from the Dashboard. It is mandatory to create the widget_id as it will be required in the API calls. A step-by-step process of creating a recommendation widget from the Dashboard is documented here.

Integrate Recommendation API: The Recommendations API requires the widget_id (created in the previous step) to be passed as a path parameter mandatorily in the API call. You might notice slight changes in the way the recommendation API requests are sent, as well as in the structure of the response body as we have. To know about the API changes pertaining to recommendations, view the Changes from V1 API ( mapping from old V1 parameters)  table here

Step 1: Upload Feed

The feed is the content of your product catalog on which the Recommendation feature works. You can upload your product feed on Bloomreach FTP site or use your own FTP site for the same. The product feed must be generated on a daily basis to keep your product data up-to-date. To learn more about generating and uploading Product Feed, click here

Note: Consult your TPM about custom changes that might be required on your product Feed for Recommendations feature.

Step 2: Integrating Pixel 

The pixel is the component that tracks the activities of your customers on your live site. Bloomreach uses customer/user behavior to optimize features dynamically.

Core Bloomreach Pixels

The core Bloomreach pixel must be implemented first for the Pathways and Recommendation pixel to work. To learn about how to install the core Bloomreach pixels, go the Pixel Deployment Page. Make sure that the core Bloomreach pixels have been live and good quality for 4 weeks. Also, allow 4 weeks after Pathways pixel is live in production to build up analytics.

For Recommendations, the events that are tracked via the pixel are:

  • View
  • Click and
  • Add-to-cart (optional)

To integrate the pixel, you must add a Javascript snippet to your code to all the pages, on all the versions- desktop, mobile, and tablet. You can simply add the tracking code snippet to your global footer to ensure it is added everywhere. Different events require different snippets and should be added individually. The events are explained below.

If you are using a Tag Manager to track event, you can setup the Bloomreach pixel without adding any code. To learn how to do this, go to Use a Tag Manager.

Supported Event Tracking Pixels 

The Javascript tracking pixels for Recommendations are tracked for the following customer activity on your live site. Each Javascript tracking pixel is defined by the BrTrk.getTracker().logEvent.

Event BrTrk.getTracker().logEvent Javascript
View
BrTrk.getTracker().logEvent('widget','widget-view',widget_view_data,true)
Click
BrTrk.getTracker().logEvent('widget','widget-click',widget_data,true) 
Add-to-Cart (optional)
BrTrk.getTracker().logEvent('cart','widget-add',widget_atc_data)

View Event Tracking Pixel

This pixel tracks the impressions of the customer whenever a recommendation widget is viewed by the customer. 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: 

  • Copy-paste the View Event Tracking Snippet given below and install it on all of your pages: 
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)

Variable Data Type Requirement Description Example
widget_data.wrid String Mandatory

The unique ID of the response. 

abcd123
widget_view_data.wq String Optional The query string used by the customer which returns a widget suggestion. This is optional for non-query widgets. black dress
widget_view_data.wid String Mandatory The widget ID. This is a unique, 6 character alphanumeric value.   abc123
widget_view_data.wty String Mandatory The type of recommendation widget. mlt,jfy, etc. 

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 install this pixel:

  • Copy-paste the Click Event Tracking Snippet given below and install it on all of your pages. 
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)
Variable Data Type Requirement Description Example
widget_data.wrid String Mandatory

The unique ID of the response. 

abcd123
widget_view_data.wq String Optional The query string used by the customer which returns a widget suggestion. This is optional for non-query widgets. black dress
widget_view_data.wid String Mandatory The widget ID. This is a unique, 6 character alphanumeric value.   abc123
widget_view_data.wty String Mandatory The type of recommendation widget. mlt,jfy, etc. 
widget_data.item_id Numeric Mandatory

The unique ID of the clicked product/ category/

content/ item.

pd123

Direct Add-to-Cart Event Tracking Pixel (Optional)

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

To track the add-to-cart event from within the widget, you must install the following Javascript tracking pixel.

  • Copy-paste the Add-to-Cart Event Tracking Snippet given below and install it on all of your pages:
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)
Variable Data Type Requirement Description Example
widget_data.wrid String Mandatory

The unique ID of the response. 

abcd123
widget_view_data.wq String Optional The query string used by the customer which returns a widget suggestion. This is optional for non-query widgets. black dress
widget_view_data.wid String Mandatory The widget ID. This is a unique, 6 character alphanumeric value.   abc123
widget_view_data.wty String Mandatory The type of recommendation widget. mlt,jfy, etc. 
widget_data.item_id Numeric Mandatory

The unique ID of the clicked product/ category/

content/ item.

id123
widget_atc_data.sku String Mandatory

Unique SKU id that represents the selected variant of this product 

(e.g. size M, color blue of a t-shirt). 

If your site does not have SKUs, leave this blank.

sku123

Validating the Pixel

The next step is to validate the pixel you have added. To know more about how to do this, go to Validate the Pixel section. 

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 type

Feed Field Required

Field values

New Arrivals

“New Arrival”

Yes/No

Brand Highlight

“Brand”

The brand name

Excess Inventory

“Excess Inventory”

Yes/No

On Sale

“On Sale”

Yes/No

New Since Last Visit

“Launch Date”

Date in the format YYYYMMDD

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: abcxyz123.

Curated widget

These widgets are manually curated and do not require any feed changes.

Category widget

Send your feed file to Bloomreach Support so they can set up your feed in a staging environment. After the feed is confirmed and running in staging, we will work with you to promote the feed to production.

Step 3: Create a Recommendation Widget (Dashboard)

The next step is to create a widget from the Bloomreach Dashboard. You can manage the widget end-to-end from the Widget Configurator in the Bloomreach Dashboard. The step-by-step process of creating a widget is given below in the Widget Configurator page. 

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.

To know more about how our APIs work, click here. To view the Pathways and Recommendations API, click here.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?