HomeEngagementContentDiscoveryOther resources
Guides

Bloomreach Discovery SDK - Old

Suggest Edits

Introduction

This SDK is currently in open beta. Contact Bloomreach with feedback.

The Bloomreach Search, Merchandising, & Recommendations SDK provides simplified integration with the Bloomreach Discovery APIs. It returns API calls along with a template user interface that your team can customize for your specific commerce store.

This SDK is currently in Beta & is used primarily to provide a quickstart UI for customers implementing Bloomreach Discovery APIs. Future versions of this SDK will allow for developers to build & access the JSON output, whereas now the Discovery API call, JSON response, and sample UI are coupled together in a single process.

Technical details

The SDK consists of 5 modules, each module can be used by including its script (and optional stylesheet) file in the page.

Commonly configurable variables in the SDK

  • Account ID
  • Domain key
  • Authentication key
  • Tracking cookie
  • Default search URL parameter name
  • URL of the search page

Example of common config variables in the Bloomreach Connector object:

bloomreachConnector.config = {
  account_id: '6621',
  domain_key: 'bornconnector_domain',
  auth_key: '123j32eqbeqaahsa',
  default_search_parameter: 'q',
  search_page_url: 'http://localhost:1234/product-search.html',
  ...
}

Modules

Autosuggest module

The Autosuggest module attaches a listener to the configured input field and shows the suggestion results under that field on every keystroke.

Installing Autosuggest module

The module can be used by including a direct link to the module files in your webpage:

<link rel="stylesheet" href="/pagenotfound" />
<script src="autosuggest.js" defer></script>

You will then have access to the module under the BloomreachModules.autosuggest object in the global scope (window).

The module loads itself automatically right after the page is fully loaded if it’s set to be enabled in the Bloomreach Connector config object.

If you need to load the module manually, you can call the load static method on it:

BloomreachModules.autosuggest.load()

What’s configurable in the Autosuggest module

  • Is it enabled or not
  • Number of term suggestions to display
  • Number of collection suggestions to display
  • Number of product suggestions to display
  • The CSS selector of the input field that the autosuggest panel will be attached to

When there are collection term suggestions, the Category module also needs to be loaded on the page and its configured selector needs to be in the DOM, so the category results can be loaded after clicking on the suggested term.

Example Autosuggest config variables in the Bloomreach Connector object:

bloomreachConnector.config = {
  ...
  autosuggest: {
    enabled: true,
    number_of_terms: 13,
    number_of_products: 14,
    number_of_collections: 15,
    selector: '.search__input'
  },
  ...
  category: {
    enabled: true,
    selector: '.main-content',
  },
  ...
}

Product Search module

The Product Search module loads in the results for the given search term into the page, and optionally the related facets as well.

For every facet change, the module re-renders the page with the filtered results.

Installing Product Search module

The module can be used by including a direct link to the module files in your webpage

<link rel="stylesheet" href="/pagenotfound" />
<script src="product-search.js" defer></script>

You will then have access to the module under the BloomreachModules.search object in the global scope (window).

The module loads itself automatically right after the page is fully loaded if it’s set to be enabled in the Bloomreach Connector config object.

If you need to load the module manually, you can call the load static method on it:

BloomreachModules.search.load()

What’s configurable in the Product Search module

  • Is it enabled or not
  • Number of results to display in one page
  • Should facets be included on the page or not
  • Number of facet groups to show initially (hidden ones can be revealed with a “+ More” link)
  • Number of facet values to show initially in a facet group (hidden ones can be revealed with a “+ More” link)
  • Should infinite scroll be used on bigger screens or not
  • The CSS selector of the container that will hold the search results
  • Sorting options for the result set that can be selected on the page in a dropdown field
  • Should the variants be expanded into the result set or not

Example Product Search config variables in the Bloomreach Connector object:

bloomreachConnector.config = {
  ...
  search: {
    enabled: true,
    items_per_page: 16,
    facets_included: true,
    initial_number_of_facets: 5,
    initial_number_of_facet_values: 6,
    infinite_scroll: false,
    selector: '.main-content',
    sorting_options: [
      {label: 'Relevance', value: ''},
      {label: 'Price (low - high)', value: 'price+asc'},
      {label: 'Name (A - Z)', value: 'title+asc'},
      {label: 'Price (high - low)', value: 'price+desc'},
      {label: 'Name (Z - A)', value: 'title+desc'}
    ],
    is_search_page: true,
    display_variants: false
  },
  ...
}

Category module

The Category module loads in the results for the current collection into the page, and optionally the related facets as well.

For every facet change, the module re-renders the page with the filtered results.

This module has the same feature set as the Product Search module.

Installing Category module

The module can be used by including a direct link to the module files in your webpage:

<link rel="stylesheet" href="/pagenotfound" />
<script src="category.js" defer></script>

You will then have access to the module under the BloomreachModules.category object in the global scope (window).

The module loads itself automatically right after the page is fully loaded if it’s set to be enabled in the Bloomreach Connector config object.

If you need to load the module manually, you can call the load static method on it:

BloomreachModules.category.load()

What’s configurable in the Category module

  • Is it enabled or not
  • Number of results to display in one page
  • Should facets be included on the page or not
  • Number of facet groups to show initially (hidden ones can be revealed with a “+ More” link)
  • Number of facet values to show initially in a facet group (hidden ones can be revealed with a “+ More” link)
  • Should infinite scroll be used on bigger screens or not
  • The CSS selector of the container that will hold the collection results
  • Sorting options for the result set that can be selected on the page in a dropdown field
  • Should the variants be expanded into the result set or not

Example Category config variables in the Bloomreach Connector object:

bloomreachConnector.config = {
  ...
  category: {
    enabled: true,
    sorting_options: [
      {label: 'Relevance', value: ''},
      {label: 'Price (low - high)', value: 'price+asc'},
      {label: 'Name (A - Z)', value: 'title+asc'},
      {label: 'Price (high - low)', value: 'price+desc'},
      {label: 'Name (Z - A)', value: 'title+desc'}
    ],
    items_per_page: 12,
    facets_included: true,
    initial_number_of_facets: 5,
    initial_number_of_facet_values: 6,
    infinite_scroll: false,
    selector: '.main-content',
    is_category_page: true,
    display_variants: false,
    category_id: '116715'
  },
  ...
}

Recommendations & Pathways module

The Recommendations & Pathways module loads the content of the different widgets into their containers on the page.

Widgets

The Bloomreach Recommendations & Pathways SDK supports 5 widget types:

Installing Pathways & Recommendations module

The module can be used by including a direct link to the module files in your webpage:

<link rel="stylesheet" href="pathways-and-recommendations.css" />
<script src="pathways-and-recommendations.js" defer></script>

You will then have access to the module under the BloomreachModules.pathwaysRecommendations object in the global scope (window).

The module loads itself automatically right after the page is fully loaded.

If you need to load the module manually, you can call the load static method on it:

BloomreachModules.pathwaysRecommendations.load()

What’s configurable in the Item type widget

  • The number of items to load into the widget
  • The number of items to show at a time in the widget
  • The item ID(s) related to load the related result set for

Example markup for placing an Item type widget in the DOM

<div
  class="blm-recommendations-widget"
  data-id="pWb1zD"
  data-type="item"
  data-item-ids="55837"
  data-number-of-items-to-fetch="16"
  data-number-of-items-to-show="4"
></div>

What’s configurable in the Keyword type widget

  • The number of items to load into the widget
  • The number of items to show at a time in the widget
  • The keyword to load the results for

Example markup for placing a Keyword type widget in the DOM

<div
  class="blm-recommendations-widget"
  data-id="kgrb9g"
  data-type="keyword"
  data-query="bed and bath"
  data-number-of-items-to-fetch="16"
  data-number-of-items-to-show="4"
></div>

What’s configurable in the Category type widget

  • The number of items to load into the widget
  • The number of items to show at a time in the widget
  • The category ID to load the items from

Example markup for placing a Category type widget in the DOM

<div
  class="blm-recommendations-widget"
  data-id="RD2X9d"
  data-type="category"
  data-number-of-items-to-fetch="16"
  data-number-of-items-to-show="4"
  data-category-id="116940"
></div>

What’s configurable in the Personalized type widget

  • The number of items to load into the widget
  • The number of items to show at a time in the widget
  • The ID of the user who will see the personalized result set

Example markup for placing a Personalized type widget in the DOM

<div
  class="blm-recommendations-widget"
  data-id="pWbBzW"
  data-type="personalized"
  data-user-id="123"
  data-number-of-items-to-fetch="16"
  data-number-of-items-to-show="4"
></div>

What’s configurable in the Global type widget

  • The number of items to load into the widget
  • The number of items to show at a time in the widget

Example markup for placing a Global type widget in the DOM

<div
  class="blm-recommendations-widget"
  data-id="MDxLyD"
  data-type="global"
  data-number-of-items-to-fetch="16"
  data-number-of-items-to-show="4"
></div>

Product Events module

The Product Events module attaches listeners to Add to Cart and Quickview items for firing these pixel events.

There are no configurable variables for this module.

Installing Product Events module

The module can be used by including a direct link to the module files in your webpage:

<script src="product-events.js" defer></script>

You will then have access to the module under the BloomreachModules.events object in the global scope (window).

The module loads itself automatically right after the page is fully loaded.

If you need to load the module manually, you can call the load static method on it:

BloomreachModules.events.load()

Example markup for placing an Add to Cart button in the DOM

<button
  data-blm-add-to-cart
  data-blm-add-to-cart-sku="Chair123"
  data-blm-add-to-cart-prod-id="60765"
  data-blm-add-to-cart-prod-name="Weathered Gray Wood Jozy Dining Chairs Set of 2"
>
  Add to cart
</button>

Example markup for placing a Quickview button in the DOM

<button
  data-blm-quickview
  data-blm-quickview-sku="Chair123"
  data-blm-quickview-prod-id="60765"
  data-blm-quickview-prod-name="Weathered Gray Wood Jozy Dining Chairs Set of 2"
>
  Quickview
</button>

UI features

The SDK comes with several template UI features to streamline your development.

Autosuggest

Under a given input field, the SDK can attach a panel for displaying the related suggestions for search terms, collections and products.

Facets

For a collection or keyword based search results, the SDK can include related facets for filtering the product list.

Search results

On a search results page, the SDK can load the product results for given search terms into the page, along with their related facets.

Recommendations

In supported widgets, the SDK can load up recommended products based on the ranking rules set within the Bloomreach dashboard.

Collections / Categories

On a collections page (also known as categories page), the SDK can load the product results for a given collection into the page, along with their related facets.

Pagination

When there are more results than the number that is configured to display in a page, pagination links can help the navigation across the result set.

Infinite scroll

On mobile screen sizes, the SDK loads more results automatically on scroll instead of using pagination links. On bigger screens, usage of infinite scroll or pagination links is configurable.

Spell correction

When there is a misspelling, Bloomreach still loads up the results for the corrected keyword automatically and the SDK informs the user about the correction.

Keyword redirection

When keyword redirection is configured, the SDK loads up the configured results set and lets the user know about the redirection.

Variant support

For products with more than one variant, the different variants can be expanded into the result set, so the variants will show up as distinct products.

Default currency

The default displayed currency is USD ($), but it can be customized by placing the following script tag into the section of the document and changing the currency value. For example:

<script> window.bloomreachDefaultCurrency = '€'</script>

Updated 5 months ago