Shopify

Get Started

Install Clerk.io on Shopify following these easy steps.

Connecting your Store #

The first step of installing Clerk.io is connecting your Store with your Clerk.io account.

The video below shows you what to do, step-by-step. Use the rest of the guide as a reference :)

After following these simple steps, you will be able to see your Live Demo Store, which gives you a personal overview of how Clerk.io will work on your webshop.

1. Add Store #

Login to my.clerk.io. The first time you do this, you will see the Add New Store page.
Write the Name and Domain of your webshop
Choose Shopify as the Platform and choose your Currency
Click Add Store

2. Configure the Shopify Connection #

From the main menu of the Setup Guide, click Sync your data
This setup guide shows what you need to do in your Shopify backend. Here is an outline of the steps:
In the Shopify backend, go to Apps > App and sales channel settings > Develop apps
Click Create an app in the top right corner
Give the app a name like “Clerk.io” and select yourself as the App developer
Click Create app
Click Configuration and find Admin API integration. Click Configure
Under Admin API access scopes, select Read access (starts with “read_”) for the following:

Customers
Inventory
Online Store Pages
Orders
Price rules
Products
Publications
Shop locales
Shopify Markets
Store Content
Translations

Click Save
Click Install App and then Install in the popup that shows
Click the API Credentials tab

3. Sync your Store #

Now copy-paste all the necessary info into the fields in my.clerk.io:

Shopify Domain (yourdomain.myshopify.com)
API key
Admin API access token
API Secret Key

Click Start Sync. Wait for the sync to finish. Maybe have a cup of coffee if you have a big product catalog ;)
That’s it!

4. Adding Clerk.io to your theme #

Install Visitor Tracking (clerk.js)

Login to the Shopify backend, and go to Online Store → Themes.
To the right of the theme you wish to install Clerk, click on "…" → Edit code.
Open the settings_schema.json file. Insert the Clerk settings snippet at the bottom of the file, just before the last ].

,  
{
"name": "Clerk settings",
"settings": [
    {
    "type": "header",
    "content": "Clerk"
    },
    {
    "type": "checkbox",
    "id": "enable_clerk",
    "label": "Enable Clerk",
    "default": true
    }
]
}

Press Save
In the left bar, under “Snippets”, click Add a new snippet called clerk-tracking, and click Done.
Insert the below Clerk.io tracking script into the file, and click Save. Remember to replace PUBLIC_KEY with your Clerk Store’s public API key.

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
    (function (w, d) {
        var e = d.createElement('script'); e.type = 'text/javascript'; e.async = true;
        e.src = (d.location.protocol == 'https:' ? 'https' : 'http') + '://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 publicKey = 'PUBLIC_KEY';
    Clerk('config', {
        key: publicKey,
        formatters: {
            currency_converter: function (price) {
                var converted_price = (price * Shopify.currency.rate);
                return (converted_price).toString();
            }
        },
        globals: {
            currency_iso: '{{ cart.currency.iso_code }}',
            currency_symbol: '{{ cart.currency.symbol }}'
        }
    });

    {% if customer %}
        Clerk('call', 'log/email', { email:  '{{ customer.email }}' });
    {% endif %}

    document.addEventListener('DOMContentLoaded', (e) => {
        (async function fetchVisitorId() {
          let visitorId = window.sessionStorage.getItem('visitor_id');
          try {
            if (!visitorId) {
              const response = await fetch(`https://api.clerk.io/v2/misc/visitor_id?key=${publicKey}&visitor=auto`);
              const data = await response.json();
              visitorId = data.visitor;
              window.sessionStorage.setItem('visitor_id', data.visitor);
            }
            Clerk('config', {
              visitor: visitorId,
            });
          } catch (error) {
            console.error('Error:', error);
          } finally {
            window.Shopify.analytics.publish('clerk_pixel_context', {
              localeApiKey: publicKey,
              visitor: visitorId,
            });
          }
        })();
      });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Open the theme.liquid file. Insert the below reference to the tracking script in the header of the document, just before the </head> tag.

{% if settings.enable_clerk %}
    {% render 'clerk-tracking' %}
{% endif %}

5. Install Order Tracking #

In the Shopify backend, go to Settings → Customer Events.
Click Add custom pixel, name it Clerk.io and click Add pixel.
Insert the below Sales Tracking Code in the code field. Click Save.
After Saving, click on connect and confirm connect.

analytics.subscribe("clerk_pixel_context", (event) => {
    browser.localStorage.setItem("clerkPixelContext", JSON.stringify(event.customData));
});

analytics.subscribe("checkout_completed", async (event) => {
    const pixelContextRaw = await browser.localStorage.getItem("clerkPixelContext");
    const pixelContext = await JSON.parse(pixelContextRaw);
    const checkout = event.data.checkout;
    fetch(`https://api.clerk.io/v2/log/sale/shopify`, {
        method: "POST",
        mode: "cors",
        body: JSON.stringify({
            sale: checkout.order.id,
            key: pixelContext.localeApiKey,
            visitor: pixelContext.visitor,
        }),
    });
});

Full installation Example #

Shopify has updated the way Private Apps are added. We are working on a new version of the video. Until then, see how to add a Private App here.

In this video you can get a complete overview of what it takes to setup Clerk.io on a Shopify webshop.

Multiple domains/languages #

The easiest way to implement Clerk.io across multiple domains in standard setups is by creating a separate Store for each domain in my.clerk.io and syncing them with each of your Shopify language domains.

This allows you to separate products, sales, currencies, etc. to keep track of each domain.

Start by creating your main Store and follow the Setup Guide to connect your Store to Clerk.io. Choose the Recommendations and/or Search that you want to display on your webshop.
When you have completed the initial setup, click "+ Add new Store" - the last option in the dropdown list (typically found below your existing Store(s) and company name):

3. On the Add New Store page, enter your domain details.

4. Click Copy from existing Store? and select the Store you want to copy content from. Then click Add Store. This will transfer the Content and Designs from your main Store.

5. Follow the Setup Guide again to activate Clerk.io by clicking on Settings -> Setup Guides to Sync Data for the new domain.

6. Once Data Sync is complete, your domain will be ready and using the same setup as your main Store.

7. Repeat this process for each of your Shopify language domains.

8. Finally, modify the tracking script in your Shopify theme to include the correct public key for each domain.

Here is an example of the tracking script modified to include multiple languages:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
  (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);

  document.addEventListener("DOMContentLoaded", (e) => {
    let publicKey;
    switch (Shopify.locale) {
      case 'nl':
        publicKey = 'KEY';
        break;
      case 'en':
        publicKey = 'KEY';
        break;
      case 'es':
        publicKey = 'KEY';
        break;
      case 'it':
        publicKey = 'KEY';
        break;
      case 'fr':
        publicKey = 'KEY';
        break;
      case 'de':
        publicKey = 'KEY';
        break;
    }

    Clerk("config", {
      key: publicKey,
      formatters: {
        currency_converter: function (price) {
          var converted_price = (price * Shopify.currency.rate);
          return (converted_price).toString();
        }
      },
      globals: {
        currency_iso: "{{ cart.currency.iso_code }}",
        currency_symbol: "{{ cart.currency.symbol }}",
        clerkShopLocale: "{{ shop.locale }}",
        template_name: "{{ template.name }}",
        clerkCountry: "{{ routes.root_url }}"
      }
    });

    ; (async function fetchVisitorId() {
      let visitorId = window.sessionStorage.getItem('visitor_id');
      try {
        if (!visitorId) {
          const response = await fetch(`https://api.clerk.io/v2/misc/visitor_id?key=${publicKey}&visitor=auto`);
          const data = await response.json();
          visitorId = data.visitor;
          window.sessionStorage.setItem('visitor_id', data.visitor);
        }
        Clerk('config', {
          visitor: visitorId,
        });
      } catch (error) {
        console.error('Error:', error);
      } finally {
        window.Shopify.analytics.publish('clerk_pixel_context', {
          localeApiKey: publicKey,
          visitor: visitorId,
        });
      }
    })();
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Remember to translate Headlines in Content -> Edit -> Select Design to the right language as well.

Multiple Inventories #

If you have a single Store with multiple inventories and languages, then you will need to create multiple Clerk.io Apps to ensure quick data sync. This is done so Stores do not share the same rate limit and restore rate in the Shopify ADMIN API.

In the Shopify backend, go to Apps > Develop apps for your Store.
Click the Create an app button, and repeat these steps until you have equivalent “Clerk.io” apps to the number of subdomains for the shop.