## 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

### 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.

### 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:

🚧



**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:

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:

#### 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**:

#### 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**:

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

## Change Log / Release Notes

1.0.10 • Pass Dynamic IDs to Recommendations Widgets • Remove character limits on input boxes • Add HTML, CSS, & Fields customization to Recommendation Widgets • Add version 2.1.0 of the SDK (Add user driven customization support for Recommendation widgets)

1.0.9 • SDK version 2.0.6 (Remove scroll to top when performing search & category page loads, fix incorrect scrolling behavior when filtering)

1.0.8 • Node version update, Shopify authentication update. • SDK version 2.0 (separate API client & UI Template code. Fixed infinite scroll behavior, swatch loading function)

1.0.7 • Performance updates when saving new values in the Shopify app

1.0.6 • SDK version 1.3.2 (enable brSegmentation value to pick up data from Bloomreach Engagement for personalized searches) • Show SDK version & App version in the UI • Enable Staging / Production endpoint selectors.

1.0.5 • Add HTML & CSS Customization capability for Search & Categories

1.0.4 • Add HTML & CSS Customization capability for Autosuggest

1.0.3 • Fix pixel inconsistencies for Recommendations widget.

1.0.2 • New App upgrade process to upgrade between new versions.

1.0.1 • Initial version - includes ability to inject sample UI into Shopify app front end for Search, Category, Recommendations, & Autosuggest calls into a Liquid powered Shopify theme.