Overview

Why upgrade

This upgrade is focused on increasing the quality of recommendations. Shopify 2.2 adds:

1. Multiple searchable data fields
2. New customer fields
3. More frequent catalog imports for data freshness: The upgrade will also re-schedule the import of catalogs from daily update to every 4 hours.

Process and upgrade overview

Upgrading to the newest version of the Shopify integration will require some preparation of the project, and upgrading both the integration and the Shopify app. Do not worry, however, as much of this process is automated, and you will find all of these steps detailed below. To leverage new web tracking, you can also update your Shopify theme Liquid templates code. After completing the prerequisites, you can perform the remaining steps in any order.

Note that upgrading to the new version will drop product catalogs and re-import them as new catalogs with some columns added, removed, or renamed. Catalogs will keep the same names. This means that, during the time of the migration, the catalogs will be empty. It also means that some previously referenced fields may not exist after the upgrade.

This can result in some of your use cases not working properly without new data mapping. This is why it is important to pause all dependant use cases before the migration, and after the migration is complete, review them before resuming.

🚧

Migration requires downtime

The migration itself takes around 5-30 minutes to re-import catalogs, depending on the size of catalogs and current instance load. We suggest to be ready for 60-90 minutes downtime. Details can be found in this article, or you can contact our support.

Upgrade guide

Prerequisites

In this step, we will prepare our project for the upgrade

Before committing to the upgrade itself, it is important to disable all active use cases and recommendations that are using Shopify product catalogs. This can be done by stopping affected campaigns:

• Web Layers, Experiments and/or Tag Manager
• Email campaigns and/or Scenarios

You can find impacted recommendation models by looking at what catalog is selected. If the catalog was created by the Shopify integration, it has a name that contains your store domain.

Upgrade the Shopify integration

In this step, we will perform the Bloomreach Engagement upgrade

This is to be updated inside your Bloomreach Engagement project.

Steps to upgrade the integration:

1. Pause the use cases (initiate a downtime if necessary)
2. Navigate to your Shopify integration in Data & Assets > Integrations > Shopify integration
3. Click the Upgrade Shopify integration button
4. Wait for a message confirming the upgrade was successful
5. Wait for another 5-30 minutes until the catalog migration finishes in the background. You will not be informed, but you can check if catalogs are populated with new items by reloading the catalog items listing.
6. Review and patch the use cases
7. Resume the use cases

Upgrade the Shopify app

In this step, we will perform the upgrade of the Shopify app

This is to be updated inside the Shopify interface by your dedicated Shopify Administrator.

1. Navigate to the Shopify Admin to manage private apps
2. Update the Webhook API version to the latest version (e.g. 2021-04)

Optional: Upgrade Web tracking

In this optional step, we will perform a web tracking upgrade

First, navigate on the GitHub repository that contains the latest version of .liquid snippets that enable standardized front-end tracking of e-commerce events on your Shopify Plus website.

Then, update your Shopify theme Liquid templates code with the updated snippets. This includes:

• product.liquid
• theme.liquid

Please, especially care to update the JS Bloomreach Engagement SDK initialization snippet (theme.liquid) to the newest version.

📘

If your snippets are already customized, add new fields as you need, use provided snippets as inspiration.

Review

In this step, we will review use cases and validate that the upgrade was successful.

Double-check that product catalogs have been recreated. You should see product catalogs with the same names, but there will be new columns. One of the columns that you can check is called tags_list, which is new in the upgraded version.

Recommendation models that have been using removed fields can be now updated to use the new version. For example, old _vendor column was replaced with brand.

You may have also used catalogs in Jinja, so remember to review and correct those advanced usages as well.

Go Live

At this point, everything should be running on the upgraded version. If downtime was necessary, now is the time to end it.