FAQ

Frontend currency conversion #

Shopify’s built-in Currency Conversion makes it easy to read the currency symbol and exchange-rate from the webshop.

By standard, Clerk.js for Shopify comes bundled with a formatter that will work as long as your 3rd party app uses Shopify’s built-in currency object.

Standard solution #

You need to use a formatter in your Designs to convert prices. This is taking an example from our standard template language here. However, when using currency conversions and symbols, then Clerk.js detects these settings such as language, currency and country code. Following examples will give you more overview of how the different components work.

In Design Editor

1.  Create a Text component where you want the price to show

2. Add the following Liquid code to show the price based on the currency converter inside the text component:

{{ currency_symbol }}{{ item.price | currency_converter }}

In HTML/CSS design (Code mode)

1. In my.clerk.io go to Search/Recommendations -> Designs and click Edit Design for your design.

2. Replace the existing money or money_eu formatter for prices, with currency_converter

3. Click Update Design.

4. You will now be able to see the converted prices and currency symbol in your design:

Shopify-frontend-api solutions #

Disclaimer: This is very custom solution to get price conversions if there are no data from the shopify API. Only use this if you are using a specific and custom setup for price conversions based on geo-ip changes.

This is the frontend solution documentation in Github.

Getting Contextual DATA JIT

This section covering how to get a contextual data in real time for showing within content returned from the Clerk.io API.

The design patterns is composed of the following parts:

• A collection containing all products.
• An alternate layout for rendering collection information as JSON.
• A Javascript Class which collects the data made available in the collection.
• A Javascript Snippet which consumes the data for the relevant product ids in a given result and places them within a div in the template.

1. The Collection

In order to ensure you have a collection with all possible products, I recommend to create a collection with a condition met by all product. The collection should be named Clerk api, as this will result in it receiving the route /collection/clerk-api frontend.

The condition for the collection should be something like price > -1000000.

2. The Alternate Layout for Collections

Second we need to create an alternate layout for showing our data using the collection.

In order to do this, we first edit the theme code for the theme we wish to use. Under the templates section in the left hand side, press Add new Template.

In the popup select collection for the resource type.

Select liquid for the file type.

Write json in the bottom most field, so that the name of the created template is collection.json.liquid.

The contents of this file should be the collection.json.liquid file found in the liquid folder for this project.

You are welcome to add field to the product in this template as required.

3. The JS Class handling data from our newly created endpoint.

In order to grab the data from our collection and prepare it so it can be used, we need to place the entire contents of index.js in our class folder in this project, inside the script tag containing Clerk.js which you have placed in theme.liquid.

It should look something like this:

This class will invalidate data based on timestamps and currencies, without you needing to change the code.

The time before invalidation is 12 hours since last building data.

Any change in currency context also invalidates the data.

4. The JS function which loads the relevant data into the template.

Lastly you should include the template.js in the design template used. The function grabs the data when available and places it in specific child elements within each product tile.

The example include the list_price and price fields.

Things to Note: If you need to use fields which are different from the price and list_price, you would add them in collection.json.liquid and then edit the template.html and template.js to also consume those fields. You should never need to edit the Class described in step 3.

Tracking multiple currencies in 1 Store #

When using multiple currencies in your Shopify webshop, it’s important that orders are translated into one currency to make sure your revenue-related performance is accurate in Clerk.io.

In the Clerk.io dashboards, your performance will always be reported in one currency. For example, if you use both GBP and DKK in your webstore, your dashboards will report performance all in GBP or all in DKK. This is why translating to one currency is important– after all, you wouldn’t want a 600 GBP purchase read by Clerk.io as 600 DKK!

To make sure your Clerk.io Dashboards show your sales data as one common currency, this can be adjusted within the Sales Tracking code you added to your store when you originally installed Clerk.io.

Head to Settings > Checkout > Additional Scripts in the Shopify backend, and change the Sales Tracking code from this:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script>
  (function (w, d) {
      var e = d.createElement('script'); e.type = 'text/javascript'; e.async = true;
      e.src = 'https://cdn.clerk.io/clerk.js';
      var s = d.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
      w.__clerk_q = w.__clerk_q || []; w.Clerk = w.Clerk || function () { w.__clerk_q.push(arguments) };
  })(window, document);
  Clerk('config', {
      key: 'yourPublicKey'
  });
  let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
  document.addEventListener('DOMContentLoaded', (e)=> {
      clerk_order_id = window.Shopify.checkout.order_id
  });
  if ( isNaN( clerk_order_id ) ) {
      if(window.Shopify){
          clerk_order_id = window.Shopify.checkout.order_id
      }
  }
  let log_sale_retry = setInterval(() => {
      if( ! isNaN( clerk_order_id ) ){
          Clerk('call', 'log/sale/shopify', {
              sale: clerk_order_id
          });
          clearInterval(log_sale_retry);
      }
  }, 100);
  </script>
  <!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
                

To this:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script>
    (function (w, d) {
        var e = d.createElement('script'); e.type = 'text/javascript'; e.async = true;
        e.src = 'https://cdn.clerk.io/clerk.js';
        var s = d.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
        w.__clerk_q = w.__clerk_q || []; w.Clerk = w.Clerk || function () { w.__clerk_q.push(arguments) };
    })(window, document);
    let clerkLocale = Shopify.locale;
    let publicKey;
    switch (clerkLocale) {
        case 'en':
            publicKey = 'yourPublicKeyEN';
            break;
        case 'fr':
            publicKey = 'yourPublicKeyFR';
            break;
        case 'de':
            publicKey = 'yourPublicKeyDE';
            break;
        // Add more cases as needed
    }
    Clerk('config', {
        key: publicKey
    });
    let clerk_order_id = parseInt("'{'+'{ checkout.order.id }'+'}'");
    document.addEventListener('DOMContentLoaded', (e) => {
        clerk_order_id = window.Shopify.checkout.order_id
    });
    if (isNaN(clerk_order_id)) {
        if (window.Shopify) {
            clerk_order_id = window.Shopify.checkout.order_id
        }
    }
    let log_sale_retry = setInterval(() => {
        if (!isNaN(clerk_order_id)) {
            Clerk('call', 'log/sale/shopify', {
                sale: clerk_order_id
            });
            clearInterval(log_sale_retry);
        }
    }, 100);
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Be sure to keep the Visitor Tracking Script the same– this is found just below the Sales Tracking code. Your orders should now flow through to the Clerk.io dashboards as one currency.

Finding common theme files #

Shopify houses over 100 different themes to style and customise your webshop. Each theme works in the same way, that you customise the theme files to get a given result on your store, however, the theme file names change from theme to theme.

Shopify gives you a search field to easily and quickly find the theme file you are looking for. If you do not know the name of the file you are looking for, you can use the search field to help locate it. For example if you are looking for the file that has the code for the search page, it is likely to have ‘search’ in the file name.

If you are unsure of whether you have found the correct file you can compare the HTML in the theme file to the HTML on the relevant page to see if they match.

This can be done on Google Chrome by right clicking on any section of the page and selecting ‘Inspect’.

You can then inspect the HTML on the page and check if the class/ID of elements are the same in the file as on the page.

If you need further assistance with this, you can also reach out to our support team.

Syncing with HTTP Auth #

Often HTTP authentication is used on staging sites to avoid uninvited visitors.

This will block the Clerk importer as well and display a 401 Unauthorized error in the sync log.

You can easily verify the importer by inserting the authentication info in the import URL like below, in Data Sync at my.clerk.io:

https://USER:PASS@www.ewksRus.com

Common sync errors #

When importing data with the Shopify integration, the webshops server is responsible for sending the product- category- and sales-data to Clerk.io.

However in some cases, the servers configuration might stop the Importer from getting access, causing an error in Data Sync.

Below is a list of the most common errors and how to fix them.

401 Server Error: Unauthorized #

This error happens if your webshop/dev environment requires HTTP authentication to access it.

This is solved simply by inserting the Username and Password as part of the Import URL:

http://username:password@awesomeshop.myshopify.com

Shopify permissions error:  This action requires merchant approval for read_content scope. #

This error usually happens if you have not given Read Access to Store content like articles, blogs, comments, pages and redirects in your Private App.

To fix it:

1. Login to Shopify and go to Apps -> Manage Private Apps -> Clerk.io (or the name you gave the App).

2. Scroll to Admin API Permissions, and click on Review disabled Admin API permissions.

3. Find Store content like articles, blogs, comments, pages and redirects and choose Read access:

4. Then scroll to the top of the page and click Save.

Handling require.js #

This guide only applies when using Clerk JS1.

In some setups, Require.js stops Clerk.js from loading, which means that no sliders or search results will be shown.

When this happens, the following error will be shown in your console:

Uncaught ReferenceError: Clerk is not defined

There are two ways to handle Require.js. Both approaches require you to make changes to the tracking-script, which is normally inserted in index.liquid.

Include “clerk” in Require.js #

The best approach is trying to get Require.js to recognize Clerk.io.

You can do this by inserting require([‘clerk’], function() {}); in the bottom of the tracking script:

Ignoring Require.js #

If the above solution doesn’t work, its possible to ignore Require.js.

You can do this by inserting window.__clerk_ignore_requirejs = true;

in the top of the tracking script:

After using one of these approaches, Require.js will now be compatible with Clerk.io.

Upgrade to Clerk.js 2 #

Clerk.js 2 is a faster and much more flexible version of our JavaScript library that makes installing Clerk.io on any webshop a breeze.

However, since the two versions work slightly differently, you need to follow these steps to successfully upgrade.

The two main differences in Clerk.js 2 is:

• The Designs in my.clerk.io use the Liquid templating language, but can also easily be created using the Design Editor.

• The script must be inserted just before the tag in your webshops template.

Step 1: Converting Designs #

Since Clerk.js 2 has a different approach Designs, you need to create new ones.

You can create your Clerk.js 2 Designs in one of two ways:

• 1. Use the intuitive Design Editor to create new Designs, as described in the following points.

• 2. Convert your old Designs. Follow this guide to see how to do it.

1.1 Start by going to my.clerk.io -> Recommendations / Search -> Designs and click New Design:

1.2 On the following screen, give your Design a Name (we recommend adding " V2" so its obvious that you are using Clerk.js2).

1.3. Choose Design Type.

1.4. Click Publish Design when you are done, and go to Step 2 in the guide.

1.5. In the Design Editor, click any of the existing elements like the name, image, button, etc. to edit it, or add new elements to the Design to add more information about products.

1.6. Click Publish This will temporarily cause them to not show up on your webshop until you are done with Step 2. Choose the new Design for all Content that should be updated. 1.7. Lastly, go to Recommendations / Search -> Content and change your Clerk.io Content to use your new Design.

1.7. There! You are now ready to switch over to Clerk.js 2.

Step 2: Replacing the script #

2.1. Start by locating the template file that is used to show all pages of the webshop, and where the original Clerk.js script is found near the bottom.

2.2. Remove the old script from the file:

2.3. Next go to my.clerk.io -> Settings -> Tracking Code. This page now contains your Clerk.js 2 tracking code.

2.4. Copy this code and insert it just before the tag in the template:

2.5. Save your template.

Congratulations! You are now running on the much-improved Clerk.js 2 setup!

You can see the full documentation for Clerk.js 2 here: https://docs.clerk.io/docs/clerkjs-quick-start