Shopify App User Guide - Bloomreach Experience - Headless Digital Experience Platform

Shopify App User Guide

Getting started

Installation

The Bloomreach Discovery Shopify App is currently in Beta. If you're interested to install the app within your Shopify store, contact a member of the Bloomreach Product team to assist you with an installation as a Custom App.

After exiting the Beta phase, you'll be able to easily install from the Shopify App Store. At that point, you can head to the Bloomreach Shopify app page and click Add app. You will be prompted with an Authorization screen. Click Install to install our application on your store.

Linking the application to your Bloomreach account

When getting started with Bloomreach, you will first work with a member of our Integrations team to create an account, import your product feed, configure searchable attributes, and get your search APIs live.

Once you finish intitial account configuration with our Integrations team, you can authenticate your Bloomreach account with your Shopify app. To do this, copy your Bloomreach account credentials into your Shopify app. You can find your credentials on your Bloomreach Dashboard, under the API keys tab.

Paste the keys into the Shopify app credentials form on the Settings page:

Copy and paste the following fields from the Bloomreach dashboard to your Shopify app:

  • Account ID

  • Domain Key

  • Auth Key

  • Search Page - the Search Results page URL. This is required by the SDK to correctly set redirect links. In Shopify, the URL is always `/search/`, for example: `https://store-domain.com/search/`

 

Installing Bloomreach on your theme(s)

To start using Bloomreach in your store, you need to install it on a theme. To install Bloomreach on a theme, navigate to the Search page and click Enable on new Theme:

Select the theme you wish to enable Bloomreach on, then click Install.

Note: If you are using a theme which also provides suggested search, such as Shopify’s Debut theme, we recommend disabling this feature before installing Bloomreach.

When you install Bloomreach, the Bloomreach app will upload a series of files to your theme and inject them into the theme’s layout file when their feature is enabled. Bloomreach uploads the following files to your theme:

Bloomreach Files

Configuration files

  • snippets/bloomreach-head.liquid

  • snippets/bloomreach-config.liquid

  • snippets/bloomreach-pixel.liquid

  • assets/bloomreach-pixel-events.js

Autosuggest files

  • assets/bloomreach-autosuggest.js

  • assets/bloomreach-autosuggest.css

  • assets/bloomreach-autosuggest-custom.css

Search files

  • assets/bloomreach-search.js

  • assets/bloomreach-search.css

  • assets/bloomreach-search-custom.css

Collection files

  • assets/bloomreach-category.js

  • assets/bloomreach-category.css

  • assets/bloomreach-category-custom.css

Recommendations files

  • sections/bloomreach-recommendations-category.liquid

  • sections/bloomreach-recommendations-global.liquid

  • sections/bloomreach-recommendations-item.liquid

  • sections/bloomreach-recommendations-keyword.liquid

  • sections/bloomreach-recommendations-personalized.liquid

 

Uninstalling Bloomreach on your theme(s)

To remove Bloomreach from a theme, navigate to the Search page and click the Delete icon next to the theme you wish to uninstall Bloomreach on. This will delete all the files previously uploaded to your theme and remove them from your theme’s layout file.

Syncing themes

If you edited one of the Bloomreach files and wish to reset it, you can sync all your installed themes again. Syncing themes allows you to re-install Bloomreach and fetch the latest versions of each file. To sync your themes, navigate to the Search page, scroll down to the Sync Themes settings form and click Sync Themes.

As a caution, if you’ve customized any of the Bloomreach files, the Sync Themes button will overwrite your changes. We recommend creating a copy of each .js, .css, or .liquid file before using Sync Themes.

 

Configuring Bloomreach

Once Bloomreach is installed, you can start to configure it.

Bloomreach App

The Bloomreach app consists of seven pages:

  1. Dashboard: News and Analytics panel.

  2. Indexing: Configuration of the indexing.

  3. Search: Theme installation, Autosuggest and Search settings.

  4. Collections: Collections configuration.

  5. Optimize: Configuration of search relevance.

  6. Recommendations: Recommendations Widgets.

  7. Settings: Credentials and Pixel settings.

Indexing

To index your feed with Bloomreach, contact your Bloomreach Integrations team. They assist with data transformation services to extract a product feed out of your Shopify instance, transform it to meet the Bloomreach Product Feed Specifications, and import to our DataConnect APIs

The product feed indexing pipeline can be configured to import a full product feed as well as enabling webhooks to import delta updates for products that change between full feed runs.

 

Autosuggest

To customize and start using the Bloomreach Autosuggest feature, navigate to the Search page, scroll down to the Autosuggest settings form, and click Customize:

From here you can:

  • Enable this feature globally for your store.

  • Change the CSS selector for the search input you wish to add autosuggest to.

  • Set the number of terms you wish to display.

  • Set the number of products you wish to display.

  • Set the number of collections you wish to display.

  • Add Custom CSS to alter the look of the autosuggest feature. 

 

Search

To customize and start using the Bloomreach Search feature, navigate to the Search page, scroll down to the Search settings form, and click Customize:

 

 

From here you can:

  • Enable this feature on the search results page for your store.

  • Set the CSS selector for the search results page content.

  • Set the number of items per page you wish to display.

  • Set whether you wish to display variants as individual products in the results

  • Set whether you wish to include facets in your results.

  • Set the number of facets you wish to display.

  • Set the number of facet values you wish to display.

  • Set whether you wish to enable infinite scroll on your search results page.

  • Add Custom CSS to alter the look of the search feature. 

 

Collections

To customize and start using the Bloomreach Collections feature, navigate to the Collections page, scroll down to the Collections settings form, and click Customize:

From here you can:

  • Enable this feature on collection pages for your store.

  • Set the CSS selector for the collections page content.

  • Set the number of items per page you wish to display.

  • Set whether you wish to display variants individually in the results

  • Set whether you wish to include facets in your results.

  • Set the number of facets you wish to display.

  • Set the number of facet values you wish to display.

  • Set whether you wish to enable infinite scroll on your search results page.

  • Add Custom CSS to alter the look of the search feature. 

 

Recommendations

To start using the Bloomreach Recommendations & Pathways Widgets, navigate to the Recommendations page, scroll down to the Enabled themes table.

Click Edit on the theme you want to add a widget to, which will open the theme editor where you can begin adding your widget.

The Bloomreach app supports five widget types:

  • Category

  • Global

  • Item

  • Keyword

  • Personalized

Select the widget type you want to display, then click Select to begin creating your widget. For example, if you want to add a Category widget, select Category then click Select.

Once you have selected a Bloomreach widget type to add to your page, you’ll be able to pair that widget in Shopify to the widget you’ve created in the Bloomreach Dashboard. On the widget create page, you can: 

  • add Widget Title (Can be any title you select. This is only for Shopify’s front end)

  • add Widget ID (Must be the Widget ID you created in the Bloomreach dashboard)

  • Collection ID (For a Category widget, it must be the Category ID used within the Bloomreach dashboard for Category ranking)

then click Save to see the widget display.

Each Widget type has different customizable options:

  • Category

    • Widget Title

    • Widget ID

    • Category ID

    • How many items to show

    • How many items to Fetch

  • Global

    • Widget Title

    • Widget ID

    • How many items to show

    • How many items to Fetch

  • Item

    • Widget Title

    • Widget ID

    • Item IDs

    • How many items to show

    • How many items to Fetch

  • Keyword

    • Widget Title

    • Widget ID

    • Keyword

    • How many items to show

    • How many items to Fetch

  • Personalized

    • Widget Title

    • Widget ID

    • How many items to show

    • How many items to Fetch

Note: All widgets rely on information provided by the tracking pixel. If the pixel is not enabled for your store, your widgets will not display properly.

 

Pixel

To start using the Bloomreach Pixel, navigate to the Settings page, then scroll down to the Pixel settings form:

From here you can, enable this feature globally for your store.

Once enabled, the Bloomreach app will inject the pixel into your theme. The pixel will track users as they navigate and interact with your site. This information is passed back to Bloomreach and adds behavioural learning data to the Bloomreach algorithm.

 

Pixel Page Views

The Bloomreach pixel tracks 7 types of page view:

  • Global Page View

  • Virtual Page View

  • Product Page View

  • Content Page View

  • Category Page View

  • Search Result Page View

  • Conversion Page View 

 

Pixel Page View Data

On each page view the Bloomreach pixel collects page specific data including:

  • Page URL

  • Customer ID

  • Product ID

  • Product SKU

  • Product Name

  • Order grand total

  • Order item info (sku, qty ordered, name, unit price)

  • Event type

 

Pixel Conversion Tracking

In order to track conversions with the Bloomreach pixel, you must also add a tracking script to the additional scripts field within your store admin. To do this: 

  • Navigate to the Bloomreach Settings and scroll down to the Pixel section.

  • When the pixel is enabled, you should see a tracking script generated directly underneath the toggle. Copy all this tracking script to your clipboard.

  • From your Shopify admin, go to Settings > Checkout.

  • Under Order processing, go to the Additional scripts text box.

  • Paste in the tracking script from your clipboard into the Additional scripts text box and click Save.

 

Pixel Events

In addition to page views and conversions, the Bloomreach pixel also tracks specific interactions the user makes on your site. The interactions tracked are:

  •  Add-to-cart Event

  •  Search Event

  •  Suggest Event

  •  Quick View Event

Search & Suggest events are captured automatically by Bloomreach. However, if you wish to capture Add-to-cart & Quick View events, you will need to make changes to the Add-to-cart & Quick View buttons throughout your themes.

For example, if you are using Shopify’s Debut theme, you can track Add-to-cart events on your product page by editing the sections/product-template.liquid file and adding the following html data attributes to the data-add-to-cart button:

data-blm-add-to-cart
data-blm-add-to-cart-sku="{{ product.selected_variant.sku }}"
data-blm-add-to-cart-prod-id="{{ product.id }}"
data-blm-add-to-cart-prod-name="{{ product.name }}"

Example Before Code:

<button type="submit" name="add"
    data-add-to-cart>
    <span data-add-to-cart-text>
    {% unless current_variant.available %}
        {{ 'products.product.sold_out' | t }}
    {% else %}
        {{ 'products.product.add_to_cart' | t }}
    {% endunless %}
    </span>
</button>

 

Example After Code, with Add-to-cart attributes:

<button type="submit" name="add"
    data-add-to-cart
    data-blm-add-to-cart
    data-blm-add-to-cart-sku="{{ product.selected_variant.sku }}"
    data-blm-add-to-cart-prod-id="{{ product.id }}"
    data-blm-add-to-cart-prod-name="{{ product.title }}">
    <span data-add-to-cart-text>
    {% unless current_variant.available %}
        {{ 'products.product.sold_out' | t }}
    {% else %}
        {{ 'products.product.add_to_cart' | t }}
    {% endunless %}
    </span>
</button>

 

If your theme also supports Quick View, you can repeat the Add-to-cart process and add the following html data attributes to the Quick View button:

data-blm-quickview
data-blm-quickview-sku="{{ product.selected_variant.sku }}"
data-blm-quickview-prod-id="{{ product.id }}"
data-blm-quickview-prod-name="{{ product.name }}"

Example Before Code:

<button name="quickview"
    data-add-to-cart>
    <span data-quickview-text>
        {{ 'products.product.quickview' | t }}
    </span>
</button>

 Example After Code, with Quick View attributes:

<button name="quickview"
    data-blm-quickview
    data-blm-quickview-sku="{{ product.sku }}"
    data-blm-quickview-prod-id="{{ product.id }}"
    data-blm-quickview-prod-name="{{ product.name }}">
    <span data-quickview-text>
        {{ 'products.product.quickview' | t }}
    </span>
</button>

 

Pixel Validator

To validate and inspect the data captured by Bloomreach pixel events, you can install the Bloomreach Pixel Validator for Google Chrome. For more details on the Pixel Validator, read the Pixel Validator documentation.

 

Customizing Bloomreach

If you want to customize Bloomreach, you can do so in a number of ways. Once you have installed Bloomreach on a theme, you can navigate to the theme editor to see the files uploaded by Bloomreach

By default, Bloomreach will not inject a feature into your theme until it is enabled. This means you are free to customize any of the core Autosuggest, Search, or Collection features as you wish, and include or enable them in your layout/theme manually. However, we recommend that you duplicate and rename the files before editing them. 

For example, if you wish to customize the autosuggest.css, navigate to the theme editor and open assets/bloomreach-autosuggest.css:

Click Add a new asset and create a blank file called my-custom-bloomreach-autosuggest.css, then click Add asset:

Copy the contents of assets/bloomreach-autosuggest.css into your new file, then click Save.

In the theme editor, navigate to layout/theme.liquid and include your custom css. Repeat this process for assets/bloomreach-autosuggest.js.

Once both files have been included in your layout/theme.liquid file, you can start customizing the Autosuggest feature to suit your needs. Because the feature is not enabled in the app, you will need to manually enable it to see your customizations on the front end. To manually enable Autosuggest, navigate to the duplicate js file assets/my-custom-bloomreach-autosuggest.js and add the following line: 

bloomreachConnector.config.autosuggest.enabled = true;

If you edited a Bloomreach file without duplicating it, you can reset the file at any time by clicking Sync Themes in the Bloomreach app settings.

Note: Any files you duplicate in this way will not be automatically removed from your theme when you uninstall Bloomreach.

 

Uninstalling Bloomreach

If you wish to uninstall the Bloomreach app from your Shopify store, we recommend uninstalling Bloomreach on all your themes first. If you uninstall the app before uninstalling the themes, your theme may end up with some leftover files and you may need to remove them manually in order to uninstall Bloomreach completely. If you need to remove these files manually, navigate to the theme and delete the files manually. For a list of files to delete, refer to the file list.

 

FAQS

How to disable the default Shopify autosuggest dropdown

After enabling the app, users can occasionally see both the default Shopify autosuggest & the Bloomreach Autosuggest on their frontend. Each Shopify theme handles the Shopify autosuggest slightly differently. To avoid this, we recommend hiding the predictive search overlay.

For example, if you are using Shopify’s Debut theme, you can hide the default Autosuggest overlay by adding the following Custom CSS:

.predictive-search-wrapper {display: none !important; }

 

Brief display of default Search & Collections pages

Because of the way Bloomreach loads & displays results on your theme, you may occasionally see the default Search & Collection pages appear for a moment before Bloomreach displays its results. To avoid this, we recommend hiding the CSS selector until Bloomreach displays the results. You can achieve this by adding some Custom CSS to the feature settings.

For example, if you are using Shopify’s Debut theme, you can hide the Search CSS selector by adding the following Custom CSS:

.template-search .main-content { visibility: hidden; }
.template-search .main-content.blm-has-loaded { visibility: visible; }

This CSS will hide the container initially and show it when Bloomreach has loaded and displayed the results. 

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?