Shopify Installation Guide

updated 4 mths ago
1reply
Andrew Hmoderator3 yrs ago

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 Hello Retail Tracking Script:

In this section, we will guide you through how to insert the Hello Retail script to your shop so that It will load in all your use-cases. To begin with, make sure you are logged into the Admin panel of your Shopify webshop. If in doubt, here is the login page: 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, then scroll down until you reach the bottom and locate the </body> tag.

Insert a line above the </body> tag, and insert copy-paste the following code below at the in-line you created in the editor window. This script includes cart tracking as well.

<script async src="https://helloretailcdn.com/helloretail.js"></script>
<script>
    window.hrq = window.hrq || [];
    hrq.push(['init', {}]);
    {% assign HelloRetailCartContentsRecreate = '' %}
    {% assign HelloRetailCartProductNumbers = '' %}
    {% for item in cart.items %}
        {% assign HelloRetailCartContentsRecreate = HelloRetailCartContentsRecreate | append: item.variant_id | append:":" | append: item.quantity | append: "," %}
        {% assign HelloRetailCartProductNumbers = HelloRetailCartProductNumbers | append: item.product_id | append: "," %}
    {% endfor %}
    hrq.push(["setCart", {
        total: {{ cart.total_price | divided_by: 100.0 }},
        url: "{{shop.url}}/cart/{{HelloRetailCartContentsRecreate}}",
        productNumbers: [{{HelloRetailCartProductNumbers}}]
    }]);
    [hr_preMoney, hr_postMoney] = "{{ 1 | money_with_currency }}".split(/[0-9,.']+/);
</script>

Lastly, scroll up and navigate to the top of the screen and click the Save button.

Inserting the Hello Retail Conversion Script:

In this section, we will guide you through how to make your conversions available for Hello Retail. This data is used across many of Hello Retail features, e.g., for enriching the algorithms of your product recommendations, and for post-conversion emails.

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 Checkout (Betalingsprocess in danish).
Now scroll down on the checkout page until you find the box Order status page with the input field Additional scripts:

If there already exists text in the Additional scripts field, go to the bottom and make a new line. We don't want to override/replace anything,

At this point you have two options depending on your setup with locales.
If you have someshop.com, someshop.com/se and someshop.com/dk you have the option of setting it up as just one shop in the hello retail dashboard, but also as individual shops. the question really comes down to the question; do you want individual conversion tracking for each locale?

5.1 Conversion tracking:

<script async src="https://helloretailcdn.com/helloretail.js"></script>
<script type="text/javascript">
    var HelloRetailProductNumbers = [];
    Shopify.checkout.line_items.forEach((item) => HelloRetailProductNumbers.push(item.product_id));
    var HelloRetailPrice = Shopify.checkout.subtotal_price;
    // the if statement below will make sure we always track the order total
    // in the shops base currency.
    // If you have a setup with multiple domains like domain.com/se and domain.com/dk
    // and dont support switching currencies within each of them individually,
    // then you can opt to remove this if statement
    // and have conversions tracked in the shops' presentment currencies.
    if (Shopify.checkout.presentment_currency != Shopify.checkout.currency) {
        var HelloRetailShippingRate = 0;
        if (Shopify.checkout.shipping_rate) {
            HelloRetailShippingRate = Number(Shopify.checkout.shipping_rate.handle.split("-").pop());
        };
        var HelloRetailTotalPrice = Number(Shopify.checkout.total_price_set.shop_money.amount);
        if (HelloRetailShippingRate && HelloRetailTotalPrice) {
            HelloRetailPrice = (HelloRetailTotalPrice - HelloRetailShippingRate).toFixed(2);
        };
    };
    window.hrq = window.hrq || [];
    hrq.push(['init', {}]);
    hrq.push(["trackConversion", {
        total: HelloRetailPrice,
        orderNumber: Shopify.checkout.order_id,
        email: Shopify.checkout.email,
        productNumbers: HelloRetailProductNumbers
    }]);
</script>

5.2 If you have individual locales you can specify the website to Hello Retail by adding an extra snippet to the code, so it ends up looking like this instead. Note that this new part needs to be adjusted your specific situation.

<script async src="https://helloretailcdn.com/helloretail.js"></script>
<script type="text/javascript">
    var HelloRetailProductNumbers = [];
    Shopify.checkout.line_items.forEach((item) => HelloRetailProductNumbers.push(item.product_id));
    var HelloRetailWebsiteUuid = "YOUR_BASE_WEBSITE_UUID";
    var HelloRetailShopLocale = Shopify.checkout.customer_locale.split("-").shift();
    switch(HelloRetailShopLocale) {
        case "se":
            HelloRetailWebsiteUuid = "YOUR_SE_LOCALE_WEBSITE_UUID";
            break;
        case "de":
            HelloRetailWebsiteUuid = "YOUR_DE_LOCALE_WEBSITE_UUID";
            break;
    };
    var HelloRetailPrice = Shopify.checkout.subtotal_price;
    // the if statement below will make sure we always track the order total
    // in the shops base currency.
    // If you have a setup with multiple domains like domain.com/se and domain.com/dk
    // and dont support switching currencies within each of them individually,
    // then you can opt to remove this if statement
    // and have conversions tracked in the shops' presentment currencies.
    if (Shopify.checkout.presentment_currency != Shopify.checkout.currency) {
        var HelloRetailShippingRate = 0;
        if (Shopify.checkout.shipping_rate) {
            HelloRetailShippingRate = Number(Shopify.checkout.shipping_rate.handle.split("-").pop());
        };
        var HelloRetailTotalPrice = Number(Shopify.checkout.total_price_set.shop_money.amount);
        if (HelloRetailShippingRate && HelloRetailTotalPrice) {
            HelloRetailPrice = (HelloRetailTotalPrice - HelloRetailShippingRate).toFixed(2);
        };
    };
    window.hrq = window.hrq || [];
    hrq.push(["init", {"websiteUuid": HelloRetailWebsiteUuid}]);
    hrq.push(["trackConversion", {
        total: HelloRetailPrice,
        orderNumber: Shopify.checkout.order_id,
        email: Shopify.checkout.email,
        productNumbers: HelloRetailProductNumbers
    }]);
</script>

Navigate to the top of the website and press Save.

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:

Configure Webshop