Shopify Installation Guide
In this guide, you can read and learn about how to set up Hello Retail with Shopify with API credentials, tracking & conversion scripts, and lastly a blank page for search.
Creating API credentials for Hello Retail:
The API credentials are used by Hello Retail to synchronise your shops products and categories with our own database, to always show updated content in our services. It is also used to get information about your orders, which is used for product relations and services such as our triggered emails.
You have to create a private application for Hello Retail. If needed, you can also read Shopify's own documentation on custom apps here.
Follow the steps below on how to do it:
- Log in to your Shopify account.
- On the dashboard view, navigate to the left-hand side menu. Click on Apps -> App and sales channel settings
- Inside this window, click on the Develop apps button.
- Click on the Allow custom app development button.
- Read and accept the warning by clicking on the Allow custom app development button.
- After accepting this, it will prompt a pop-up to verify this change and the App development overview will look like this as seen below.
- Next, click on the Create an app button.
- Inside the Create an app view, input an App name associated with Hello Retail. Then choose the App developer appropriate from your company.
Note It is only possible to assign staff and collaborators with permission to develop apps.
- When you have entered the details, then click on the Create button.
- Next, the overview of the created app will look like this. Click on the Configure Admin API scopes button.
- Inside the search bar for Filter access scopes, search individually for:
Customers - read_customers
Orders - read_orders
Product listings - read_product_listings
Products - read_products
Store content - read_content
Translations - read_translations
- With all these scopes, enable the read ability for all of them.
- In the Configuration tab, you have the option to see an overview of the access scopes listed with reading access.
- After the completion, click on the green Install app button to prompt the Admin API access token. Copy this generated token.
- Now that the following steps have been completed, please send the API Key and the API Access Token to support@helloretail.com with the following details:
- API Key
- Admin API Access Token
- Your Shopify store name (xxx.myshopify.com)
- To find the API, go to the API credentials tab and copy & paste the information.
Inserting the Helloretail.js script
In this section, we will guide you on how to insert the Hello Retail script on you pages.
log into the Admin panel of your Shopify webshop: shopify.com/login.
- On the dashboard view, navigate to the left-hand side menu. Click on Online Store.
- From the drop-down menu, click on Themes.
- Navigate over to the right-hand side to Debut and click on the drop-down button of Actions.
- From the drop-down menu, click on Edit code.
- On the left-hand side, a second menu bar will prompt. In this menu, go down to the folder named Layout and click on the file named theme.liquid. Next, an editor window will appear.
- Inside the editor window scroll down towards the bottom until you locate the end of the </body> tag.
Copy the following code snippet, and paste it on new line just above the end tag.
<script async src="https://helloretailcdn.com/helloretail.js"></script>
<script>
let helloRetailInitParams = {};
if (Shopify.country) {
switch (Shopify.country) {
case "US":
helloRetailInitParams.websiteUuid = "YOUR_US_WEBSITE_UUID";
break;
case "DK":
helloRetailInitParams.websiteUuid = "YOUR_DK_WEBSITE_UUID";
break;
}
// ignore if the snippet was inserted without updating the websiteUuid.
if (helloRetailInitParams.websiteUuid && helloRetailInitParams.websiteUuid.startsWith("YOUR_")) {
delete helloRetailInitParams.websiteUuid;
}
}
if (Shopify.customerPrivacy) {
let hr_trackingIsAllowed = Shopify.customerPrivacy.analyticsProcessingAllowed() && Shopify.customerPrivacy.marketingAllowed();
if (!hr_trackingIsAllowed) {
helloRetailInitParams.trackingOptOut = true;
}
}
if (Shopify.currency && Shopify.currency.active && Shopify.currency.rate) {
let date = new Date();
date.setTime(date.getTime() + (60 * 24 * 365 * 60 * 1000));
let domain = window.location.host;
if (domain.indexOf("www.") === 0) {
domain = domain.substring(4);
}
document.cookie = "hello_retail_currency" + "=" + encodeURIComponent(JSON.stringify(Shopify.currency))
+ "; expires=" + date.toGMTString()
+ ";domain=." + domain
+ ";path=/;samesite=lax";
}
window.hrq = window.hrq || [];
hrq.push(["init", helloRetailInitParams]);
document.addEventListener("visitorConsentCollected", (event) => {
let hr_trackingIsAllowed = Shopify.customerPrivacy.analyticsProcessingAllowed() && Shopify.customerPrivacy.marketingAllowed();
hrq = window.hrq || [];
hrq.push(function(sdk) {
sdk.setTrackingOptOut(!hr_trackingIsAllowed);
});
});
</script>Note: The section for setting websiteUuid based on Shopify.country can be ignored, if your Shopify setup only has one language or country version, or indeed if Hello Retail doesn't need to do different things on these. The code is there to handle the fact, that while Shopify automatically supports different languages on the same domain, in Hello Retail these will need to be defined as separate "websites". It is also possible to use Shopify.locale instead of Shopify.country if that matches your Hello Retail setup better. If you do not change this code, the rest of the script will handle it, so that Hello Retail is added to the default language/country.
Note: The variable hr_trackingIsAllowed is based on the combined return values of
Shopify.customerPrivacy.analyticsProcessingAllowed() and Shopify.customerPrivacy.marketingAllowed()
Make sure to update this logic if the default case does not apply to your store.
Other calls available from customerPrivacy:
Shopify.customerPrivacy.marketingAllowed() and Shopify.customerPrivacy.saleOfDataAllowed()
Lastly, scroll up and navigate to the top of the screen and click the Save button.
Inserting the Hello Retail tracking pixel:
In this section, we will guide you on how to make your carts and conversions available for Hello Retail. The data is essential in optimising our algorithms, tuning the content and for features like our triggered emails.
Note: if you are updating an existing installation, make sure you remove the old parts first: remove-old-shopify-scripts
- When logged in as Admin: Navigate to the left-hand menu and click on Settings at the bottom of the screen - a popup window with settings will appear.
Click on the menu for Customer events and then on the button Add custom pixel in the top right corner.
A popup will appear and ask for a name, just call it something meaningful like "Hello Retail Pixel" and click the Add Pixel button.
- Now copy the code snippet from below and insert it into the code field of your new custom pixel. When you have inserted it make sure to press the Save button.
function trackCart(helloRetailId, helloRetailWebsiteUuid, helloRetailCurrency, event, init) { let cartLinesMap = {}; let cartPayload = { 'trackingUserId': helloRetailId, 'websiteUuid': helloRetailWebsiteUuid, 'total': 0, 'url': event.context.document.location.origin + '/cart/', 'productNumbers': [], }; // init.data.cart represents a snapshot of the cart when the event was triggered. // So the init.data.cart will be one step behind the new state triggering the event. // this means the init.data.cart will be empty on the first "product_added_to_cart" event. const existingCart = init.data.cart; let currencyCode = null; if (existingCart) { cartPayload.total = existingCart.cost.totalAmount.amount; currencyCode = existingCart.cost.totalAmount.currencyCode; existingCart.lines.forEach((existingLine) => { // merchandise.id is variant id // merchandise.product.id is main id cartLinesMap[existingLine.merchandise.id] = existingLine; }); } const cartLineUpdate = event.data.cartLine; if (cartLineUpdate) { currencyCode = cartLineUpdate.cost.totalAmount.currencyCode; const lineQtyUpdate = cartLineUpdate.quantity; const lineIdUpdate = cartLineUpdate.merchandise.id; const isRemoveFromCart = event.name == "product_removed_from_cart" ? true : false; if (isRemoveFromCart) { if (lineIdUpdate in cartLinesMap) { cartLinesMap[lineIdUpdate].quantity -= lineQtyUpdate; if (cartLinesMap[lineIdUpdate].quantity <= 0) { delete cartLinesMap[lineIdUpdate]; } } cartPayload.total -= cartLineUpdate.cost.totalAmount.amount } else { if (lineIdUpdate in cartLinesMap) { cartLinesMap[lineIdUpdate].quantity += lineQtyUpdate; } else { cartLinesMap[lineIdUpdate] = cartLineUpdate; } cartPayload.total += cartLineUpdate.cost.totalAmount.amount } } Object.values(cartLinesMap).forEach((currentCartLine) => { // merchandise.id is variant id // merchandise.product.id is main id cartPayload.productNumbers.push(currentCartLine.merchandise.product.id) cartPayload.url += (currentCartLine.merchandise.id + ":" + currentCartLine.quantity + ","); }); if (helloRetailCurrency && helloRetailCurrency.code == currencyCode) { cartPayload.total = Number(cartPayload.total / helloRetailCurrency.rate).toFixed(2); } else if (event.name == "checkout_started") { // Our currency doesnt match the current currency presented. // Most likely this is due to shopify auto changing the currency based on shipping address. // We have likely tracked a cart already at this point, so we can just ignore this event. // There is also the chance the customer will go back to the shop, // in which case our currency will be updated and we will be able to track correctly next event. return; } fetch('https://core.helloretail.com/serve/collect/cart', { method: 'POST', headers: { 'Content-Type': 'text/plain' }, body: JSON.stringify(cartPayload), keepalive: true, }); } function trackConversion(helloRetailId, helloRetailWebsiteUuid, helloRetailCurrency, event) { const checkoutData = event.data.checkout; if (checkoutData) { let totalInBaseCurrency = null; if (helloRetailCurrency && helloRetailCurrency.code == checkoutData.subtotalPrice.currencyCode) { // only set total when we are able to convert to base currency. totalInBaseCurrency = Number(checkoutData.subtotalPrice.amount / helloRetailCurrency.rate).toFixed(2); } let products = []; checkoutData.lineItems.forEach((lineItem) => { // lineItem.id is variant id // lineItem.variant.product.id is main id products.push({ 'productNumber': lineItem.variant.product.id, 'url': event.context.document.location.origin + lineItem.variant.product.url, 'quantity': lineItem.quantity, 'lineTotal': lineItem.variant.price.amount }) }); const conversionPayload = { 'trackingUserId': helloRetailId, 'websiteUuid': helloRetailWebsiteUuid, 'total': totalInBaseCurrency, 'orderNumber': checkoutData.order.id, 'email': checkoutData.email, 'products': products } fetch('https://core.helloretail.com/serve/collect/conversion', { method: 'POST', headers: { 'Content-Type': 'text/plain' }, body: JSON.stringify(conversionPayload), keepalive: true, }); } } function trackCustomerEmail(helloRetailId, helloRetailWebsiteUuid, event) { const checkoutData = event.data.checkout; if (checkoutData) { const trackingUserPayload = { 'trackingUserId': helloRetailId, 'websiteUuid': helloRetailWebsiteUuid, 'email': checkoutData.email, } fetch('https://core.helloretail.com/serve/collect/customerEmail', { method: 'POST', headers: { 'Content-Type': 'text/plain' }, body: JSON.stringify(trackingUserPayload), keepalive: true, }); } } async function getWebsiteUuid(browser) { const helloRetailState = await browser.sessionStorage.getItem('hello_retail_state'); let helloRetailWebsiteUuid = null; if (helloRetailState) { const helloRetailStateJSON = JSON.parse(helloRetailState); helloRetailWebsiteUuid = helloRetailStateJSON.website.uuid; } return helloRetailWebsiteUuid; } async function getHelloRetailId(browser) { return (await browser.cookie.get('hello_retail_id')) || null; } async function getHelloRetailCurrency(browser) { const currency = await browser.cookie.get('hello_retail_currency'); if (!currency) { return null; } const currencyObj = JSON.parse(decodeURIComponent(currency)); return {"rate":currencyObj.rate, "code":currencyObj.active}; } analytics.subscribe('product_added_to_cart', async (event) => { const helloRetailId = await getHelloRetailId(browser); const helloRetailWebsiteUuid = await getWebsiteUuid(browser); const helloRetailCurrency = await getHelloRetailCurrency(browser); if (helloRetailId && helloRetailWebsiteUuid) { trackCart(helloRetailId, helloRetailWebsiteUuid, helloRetailCurrency, event, init); } }); analytics.subscribe('product_removed_from_cart', async (event) => { const helloRetailId = await getHelloRetailId(browser); const helloRetailWebsiteUuid = await getWebsiteUuid(browser); const helloRetailCurrency = await getHelloRetailCurrency(browser); if (helloRetailId && helloRetailWebsiteUuid) { trackCart(helloRetailId, helloRetailWebsiteUuid, helloRetailCurrency, event, init); } }); analytics.subscribe('checkout_started', async (event) => { // This is used for cart tracking in the case of "direct to checkout". // also works as a failsafe in the case a user returns to the shop, // has an active cart and goes directly to checkout. const helloRetailId = await getHelloRetailId(browser); const helloRetailWebsiteUuid = await getWebsiteUuid(browser); const helloRetailCurrency = await getHelloRetailCurrency(browser); if (helloRetailId && helloRetailWebsiteUuid) { trackCart(helloRetailId, helloRetailWebsiteUuid, helloRetailCurrency, event, init); } }); analytics.subscribe('checkout_contact_info_submitted', async (event) => { const helloRetailId = await getHelloRetailId(browser); const helloRetailWebsiteUuid = await getWebsiteUuid(browser); if (helloRetailId && helloRetailWebsiteUuid) { trackCustomerEmail(helloRetailId, helloRetailWebsiteUuid, event); } }); analytics.subscribe('checkout_completed', async (event) => { // Shopify customer events will only fire if the customer has opted in. const helloRetailId = await getHelloRetailId(browser); const helloRetailWebsiteUuid = await getWebsiteUuid(browser); const helloRetailCurrency = await getHelloRetailCurrency(browser); if (helloRetailId && helloRetailWebsiteUuid) { trackConversion(helloRetailId, helloRetailWebsiteUuid, helloRetailCurrency, event); } }); - Now you can set the appropriate customer privacy settings and press the Connect button to publish the tracking pixel:
Note: If you, prior to completing the section above, deleted an older installation, then make sure that you follow this section from the guide, in order to have the general tracking script inserted on your webshop.
Creating a Blank Page for the Hello Retail Search:
The following section is only relevant for setups for a full search.
Step 1: Navigate and click "Online store"
Step 2: Click sub-menu "Pages"
Step 3: Navigate to the top right corner and click the button "Add pages". A new page editor will appear.
Step 4: In the page editor, please write a meaningful title, e.g., "Search results" in Title. Make sure the option "Visible" is chosen under Visibility. Choose "page" under Template.
Step 5: Navigate to the bottom right corner and press button "Save"
Step 6: You have now created a blank page for Hello Retail to display search results. After you clicked the save button, please navigate to the top of the page and locate and "View Page." This will open a new tab in your browser.
Step 7: Find the URL near your browser tab, copy-paste it, and share it with Hello Retail so they can finish your full-page search.
Configure Webshop
After the installation setup of your platform and the onboarding flow, make sure to have your webshop configured. Read this guide here on how to do so:
Updating Your Shopify Integration
The steps for updating your Hello Retail Shopify integration depend on the version of your current setup.
Legacy Integration (No Tracking Pixel)
If your integration uses a script in the “Additional Scripts” field of the checkout.liquid page (i.e., no tracking pixel):
Follow the Remove Old Shopify Scripts guide to remove the legacy integration.
Then follow the Shopify Integration Setup guide from the beginning to install the latest version.
Older Version of Current Integration (With Tracking Pixel)
If you're already using a tracking pixel but need to update:
API Credentials:
Refer to Creating API Credentials for Hello Retail step 11. Ensure your API credentials have all required permissions.HelloRetail.js Script:
Verify that the embedded script matches the latest version in the guide. We recommend copying and replacing it to ensure accuracy.Tracking Pixel:
Ensure the tracking pixel implementation matches the current documentation. Again, copying and replacing is the safest approach.