Functional Specification for Bloomreach Connector Apps

As customers consider a Bloomreach Discovery integration through a connector, many still have goals to customize the experience on top of the connector. The table below lists the functional specifications of the Bloomreach Connectors. The Discovery Connectors consist of a Product Feed export and an App User Interface (where a user configures the behavior of the sample UI that gets injected into the Commerce Platform) and is powered by an SDK that is used by the Shopify, Bigcommerce, & Magento apps.

Here is a breakdown of functional and technical details that clarify what is offered and how much customization is possible to help you understand when you may need to go down a custom integration path instead of a connector.

Product Feed

ConnectorFunctional SpecificationFull Feed SupportedDelta Feeds SupportedConfiguration
ShopifyOur suggested approach is to use our Shopify Reference Architecture. This includes a set of reference code that your team can download, customize, and host.

This uses the most reliable and fast mechanism to pull the product feeds out of Shopify's Bulk Operations endpoint.
YesNoFully configurable by the customer.
BigcommerceOur suggested approach is to have Bloomreach Services set up a feed integration via an internal ETL tool.

This allows light data model customization and can be set to run on a predetermined cadence.
This approach relies on the Bigcommerce GraphQL API, and is subject to rate limits when pulling data from Bigcommerce.
Full feeds typically take 2-4 hours to extract.
YesYesNo customer-facing configuration. A moderate amount of configurations can be performed by the Bloomreach Services team.
MagentoOur suggested approach is to have Bloomreach Services set up a feed integration via an internal ETL tool.

This allows light data model customization and can be set to run on a predetermined cadence. This approach relies on the Magento GraphQL API and is subject to rate limits when pulling data from Magento.
Full feeds typically take 2-4 hours to extract.
YesNoNo customer-facing configuration. A moderate amount of configurations can be performed by the Bloomreach Services team.

Alternatively, other common methods have been to use the XTENTO Magneto extension to extract products from Magneto, transform them, and import them to the Bloomreach DataConnect API.


FeatureFunctional SpecificationConfiguration
AutosuggestThe Autosuggest UI renders data contained in the API response for:

  • Suggested Terms
  • Suggested Products
  • Suggested Product Images
  • Suggested Collections (known as Categories for Bigcommerce & Magento)
  • You can set the number that gets displayed inside the Commerce Platform App for Collections, Terms, Products.

    You can turn off Collections, Terms, or Products within the Autosuggest UI.

    Keyword Search

    FeatureFunctional SpecificationConfiguration
    SortBy default, include sorting by:

  • Title (A/Z and Z/A)
  • Price (Low/High and High/Low)
  • Best Seller (Default BR search response)
  • Not configurable in the Connectors. You do not need to select additional or exclude certain sort parameters.
    PaginationDesktop: Required by default. The default page loads 16 products, which can be increased by factors of 4 to a maximum of 48.

    Mobile: Not required. Uses Lazy load / infinite scroll.
    You can select between standard pagination, or infinite scroll from within the app.

    If using standard pagination, you can select the numbers that are included in the grid page and in the grid page selector dropdown.
    RedirectWithin the Bloomreach Dashboard, you can set up a redirect for a search term (i.e. "Chair" automatically returns a result for "Stool"). The search result will come back as the redirected term, but the UI also indicates "Redirected from [original search term]". If the API response contains "keywordRedirect", the Connector incorporates the redirected URL.

    Both relative and absolute redirects are supported to work with the connectors:
    • If the redirect starts with a “/“ then it is a relative redirect (redirects internally within the domain/site)

    • Anything else is treated as an absolute redirect (redirects to the exact URL inputted and can also include external sites), with “http(s)” auto-prepended

    The Search results page also includes the number of results found, and accounts for Bloomreach spell correction ("did_you_mean" section in JSON response).
    Product HierarchyIf a product has variants, the Product Grid includes variant images/color swatches. Feeds contain a full image and thumbnail image for every variant, so those images are displayed in the grid for both Search results and Categories.By default, each variant is displayed in search results as its own product.

    You can collapse the variants under one product so that only the parent product will be displayed, which can be toggled under Search Options. In this case, the parent product displays swatches in the UI for different variants.
    Product Item DisplayIn the Product Grid, each product returns the following:

  • Title
  • Original Price
  • Sale Price (if present), Original Price (with strikethrough)

  • If custom metafield attributes are present in the API response, the Connector SDK passes them through. In this case, you will need to custom build the UI, and cannot manage the UI in the app.

    Does not include:

  • "On Sale" tag
  • ratings
  • promotions
  • The HTML of the Product Item cards is configurable directly within the app.
    Pricing DisplaySee Product Item Display above for basic pricing (Original Price, Sale Price).

    For the Connector SDK, when swatches/variants are displayed, we also display a Price Range (for products whose variants have a range in price). Price Range is included in the API payload.
    The HTML of the Product Item cards is configurable directly within the app.
    Real-time Product Information (price, availability, etc.)All pricing updates will be based on the latest feed we've indexed.

    No additional real-time capability is supported in the Discovery SDK.
    Not configurable in the Connectors


    FeatureFunctional SpecificationConfiguration
    Commodity Features:
  • multi-select
  • result counts
  • When facets are returned, the Connector SDK gives the option to select multiple facet values, and can display the number of items/results within that facet.You can select how many facets to display in a standard Search Results or Collection page. If there are more facets to display, the UI includes "Show more".
    Range facetsThe Price Range facet is at the top of the facet list. The Connector SDK displays the facet value for Price Range if it exists in the API response.

    The ranges are set by Bloomreach in the Bloomreach Dashboard, and are included in the API response.
    Does not need to be configured. The Connector SDK returns the result from Bloomreach and renders it as a Price Range facet
    Facet Value HierarchyBy default, Facet Value displays 4 values, and includes a "+ More" sign to expand the full list of Facet Values. This also applies to Facets.Within the app, you can configure the number of values to display before the "+ More" sign.


    FeatureFunctional Specification
    Category BannersNot supported. Even if the API response contains banners, the Connector SDK does not need to display it.
    TaxonomyWhen making an API call to the Bloomreach Category API, the Connector SDK displays the correct category products in the front end.
    Feature Parity with Search PLPThe UI for the Search Results Page and Category page should be at parity with each other.

    Recommendations & Pathways

    FeatureFunctional SpecificationConfiguration
    Pathways and Recommendations - ShopifyYou can make a Shopify CMS component for Recommendations that can accept a Bloomreach Recommendations Widget ID. This widget ID is saved in the Shopify CMS and includes the pixel event for Recommendations.This is configurable in Shopify.
    Pathways and Recommendations - SDKThe SDK accepts a Bloomreach widget ID from the commerce platform front end, which will be passed in the API call to Bloomreach.

    The SDK takes the Bloomreach Pathways and Recommendations API and returns a 4 wide product grid that contains the image, title, price, sales price. The grid also has carousel arrows to display more items, up to 16 responses.

    When there are multiple Recommendations widgets on a single page, the SDK accepts and returns the correct widget ID for each widget's API call.

    Edge Case: If the API doesn't return any results, the product grid will not be displayed or included on the page.
    You can drag and drop a new Recommendations widget from the commerce platform CMS.

    You can also select how many products are displayed in each grid (default: 4 wide), and the total amount of products to include in the carousel (default: 16). If the UI is responsive, the grid will auto widen/shrink.
    MLT, JFY, BestsellersAll Recommendations and Pathways widgets will be rendered the same, regardless of the underlying algorithm.

    Not supported in the Discovery SDK.


    FeatureFunctional SpecificationConfiguration
    Tag Management SolutionThe Shopify App injects the Pixel throughout the front end powered by the commerce platform. The Pixel should be present on these pages:

  • Home page
  • Search Results page
  • PDP
  • Category page
  • Checkout, Add to cart pages
  • Not configurable. The Pixel is automatically injected once the API Key/Secret has been configured.

    Which Bloomreach features are not supported in the Connectors?

    Feature GroupUnsupported Features
  • Content Search suggestions
  • Predictive result counts
  • B2B
  • Contract / Entitlement Based Pricing
  • Autosuggest: Product Suggestions
  • Customer Part Number Lookup
  • Categories
  • Sub-category Product Lists
  • Non-PLP Landing Pages
  • Dynamic Categories
  • Content Search
  • Content Sources
  • Facets
  • Mixed Display
  • Conditional Facet Display
  • Unified ranking (v3 facet response)
  • Keyword Search
  • Searchable ID Fields
  • Collections / Bundles
  • Keyword Banners
  • Dynamic Grouping
  • Group merchandising
  • Personalization
  • 1:1 Personalization
  • Targeting / Audiences
  • Relevance by Segment
  • RecommendationsVisual Search