To integrate Recommendations and Pathways, 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 given below:

Step 1: Upload Feed

Step 2: Integrate Pixel

Step 3: Create a Widget

Step 4: Integrate Recommendations API 

📘

Activate Widget Feature

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

Note: If you're integrating Third-Party Widget Pixels instead, you do not need the Widget Feature activated.
Read more about Third-Party Widget Pixels here.

🚧

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) through the Catalog Management APIs 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
- Recommendations and Pathways 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 Recommendations and Pathways, 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 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 learn 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. Learn about generating and uploading Product Feed, in the Full Product Feed page.

👍

Note

Consult your Bloomreach representative about the 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 Recommendation and Pathways pixel to work. To learn about how to install the core Bloomreach pixels, go to the Pixel Deployment Page. Also, allow 4 weeks after the Pathways pixel is live in production to build up analytics.

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

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

For integrating Third-Party Pixels (Non-Bloomreach powered), refer to this section.

2a: Integrating Bloomreach Powered Pixels

This section lists the supported Event Tracking Pixels and how you can integrate them.

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.

BrTrk.getTracker().logEvent('widget','widget-view',widget_view_data,true)

BrTrk.getTracker().logEvent('widget','widget-click',widget_data,true)

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 snippet below 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)

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:

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)

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, install the following Javascript tracking pixel snippet below 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)

2b: Integrating Non-Bloomreach Powered Pixels

If you are using Third-Party recommendation widgets (not powered by the Bloomreach Discovery platform) on your Search, Category, and Product pages, we recommend integrating Third-Party Widget Pixels, which will optimize the data that Bloomreach Discovery learns from.

Third-Party Widget Pixels are of the same format as the Recommendations and Pathways Widget Pixels with specific values for certain parameters, which are mentioned in the tables.

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.

BrTrk.getTracker().logEvent('widget','widget-click',widget_data,true)

BrTrk.getTracker().logEvent('cart','widget-add',widget_atc_data)

View Event Tracking Pixel

You don't need to integrate the View Event Tracking Pixel for Third-Party Widgets.

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:

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)

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, install the following Javascript tracking pixel snippet below on all of your pages:

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)

Validating the Pixel

The next step is to validate the pixel you have added. To learn more, read the Pixel Validation page. 

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:

📘

Curated widget and Category widget

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

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. View the detailed documentation on the Recommendations and Pathways API page. 

Learn more about how our Bloomreach Search and Merchandising APIs work.