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 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) 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
- 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)
| Variable | Data Type | Requirement | Description | Example |
|---|---|---|---|---|
| widget_view_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. The value returned in the API response shall be passed as a widget type. | 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 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)
| Variable | Data Type | Requirement | Description | Example |
|---|---|---|---|---|
| widget_data.wrid | String | Mandatory | The unique ID of the response. | abcd123 |
| widget_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_data.wid | String | Mandatory | The widget ID. This is a unique, 6 character alphanumeric value. | abc123 |
| widget_data.wty | String | Mandatory | The type of recommendation widget. The value returned in the API response shall be passed as a widget type. | mlt,jfy, etc. |
| widget_data.item_id | String | 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, 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)
| Variable | Data Type | Requirement | Description | Example |
|---|---|---|---|---|
| widget_atc_data.wrid | String | Mandatory | The unique ID of the response. | abcd123 |
| widget_atc_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_atc_data.wid | String | Mandatory | The widget ID. This is a unique, 6 character alphanumeric value. | abc123 |
| widget_atc_data.wty | String | Mandatory | The type of recommendation widget. | mlt,jfy, etc. |
| widget_atc_data.item_id | String | 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 |
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-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
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)
| Variable | Data Type | Requirement | Description | Example |
|---|---|---|---|---|
| widget_data.wrid | String | Mandatory | Set the value to br_ext. | br_ext |
| widget_data.wid | String | Mandatory | Set the value to br_ext. | br_ext |
| widget_data.wty | String | Mandatory | Set the value to br_ext. | br_ext |
| widget_data.item_id | String | 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, 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)
| Variable | Data Type | Requirement | Description | Example |
|---|---|---|---|---|
| widget_atc_data.wrid | String | Mandatory | Set the value to br_ext. | br_ext |
| widget_atc_data.wid | String | Mandatory | Set the value to br_ext. | br_ext |
| widget_atc_data.wty | String | Mandatory | Set the value to br_ext. | br_ext |
| widget_atc_data.item_id | String | 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 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:
| 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 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.