clerk.io

When Clerk does not have a prebuilt extension or integration for a given webshop platform, we refer to it as a custom platform.

The biggest difference is that custom platforms should sync with a Data Feed and insert Clerk results to the frontend.

This guide explains how to install Clerk on a custom platform using Clerk.js. This is the recommended approach as it takes care of much of the heavy lifting in terms of tracking and API calls.

Clerk.js is a lightweight library that allows setting up Clerk using simple HTML snippets in the source code. Clerk.js will scan the page for any snippets with the class “clerk” and use them to make API calls.

These are the 4 steps you will go through when installing Clerk:

Sync data
Track behaviour
Visualise results
Add results to frontend

1. Sync data #

1.1 Set up a Store #

Each Clerk setup is configured on a Store in my.clerk.io. This will contain all the data you upload, and allow you to interact with it through it’s Public API key.
If you need to setup multiple webshops or domains, each should have their own Store.
You can copy your configuration to new Stores after doing the first setup

1.2 Build JSON Data Feeds #

This is the main source of data from the webshop to Clerk. Check the specification for the feeds here.
- The feeds should ideally be updated once a day on your side
- The feeds should be hosted at a URL where Clerks importer can fetch it. e.g. https://awesomestore.com/feed/clerk.json
- As a baseline, the feeds should always contain all available products and categories, but can also contain pages (blog posts / articles) and customer data.
- On the first import, you should include all historic orders. After the first import, these can be removed as Clerk keeps them in the database.
- For products, apart from the required ones, you can send any other attributes that are important for your business, like reviews, colors, labels, splash-images etc.
- Clerk uses product attributes for searching, filtering and styling.
By default, Clerk will import the feeds at least once a day.
You can configure a window within 1 hour (e.g. between 2:59-3:59) if you want the importer to run at a specific time.

1.3 Realtime updates #

This is optional but recommended.
If the webshop requires updates in realtime, like removing out-of-stock products or updating prices, our CRUD API can be used to add, update or remove products between feed imports.

2. Track behaviour #

2.1 Install Clerk.js #

Clerk tracks clicks, searches and orders from the frontend for three key reasons:
- Letting the AI learn about customer behaviour in realtime through the orders
- Analytics that shows which orders were impacted by Clerk and how much more they are worth
- Personalising various Recommendations across the site
The Clerk.js script should be added with your other scripts in the <head> section, and configured with the Public API Key found in my.clerk.io.
This will load the library that generates cookieless, anonymous visitor IDs and it will track clicks on any products shown by Clerk through the snippets.

<!-- 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);

  Clerk('config', {
    key: 'insert_api_key'
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

2.2 Add sales-tracking #

This should be added to your order success page.
Update the placeholders to fetch the correct data from the orders.
Whenever an order is placed, Clerk.js will use the snippet to make an API call to Clerk containing the order information.

 <span
    class="clerk"
    data-api="log/sale"
    data-sale="123456"
    data-email="luke@skywalker.me"
    data-customer="7890"
    data-products='[{"id": 12, "quantity": 1, "price": 99.95}, {"id": 54, "quantity": 2, "price": 9.50}...]'>
</span>

Clerk also logs the products viewed by visitors, for personalising in certaing banners.
If you will be using Cross-Sell and/or Alternative products on your product detail pages, Clerk will use these to log the product(s) viewed by visitors.
If not, you must include this snippet on the product detail page to log the product views as well:

<span 
    class="clerk"
    data-api="log/product"
    data-product="INSERT_PRODUCT_ID">
</span>

3. Visualise results #

When using Clerk.js, designs can be handled in two ways:
- Hosted in my.clerk.io using either our Design Editor or Liquid code
- Hosted in your source code as embedded results

Hosting designs in my.clerk.io, offers most flexibility, as you can change designs, logics and filters without changing your onsite code after the setup. The drawback is that designs are handled on a per-store basis.
Hosting designs in your source code gives you the freedom to share designs across multiple Stores, but the drawback is that you cannot use our Content system to make changes to the results.

4. Add snippets to frontend #

This is done with Content snippets in Clerk.js.
To insert Clerk results, choose a Content in my.clerk.io, set a design you created the design you have created and copy the snippet to the page where it should be shown. Examples:

<!--Best Alternatives Recommendations-->
<span 
    class="clerk"
    data-template="@product-page-alternatives"
    data-products="[INSERT_PRODUCT_ID]">
</span>

<!--Instant Search-->
<span 
    class="clerk"
    data-template="@live-search"
    data-instant-search="INSERT_SEARCH_INPUT_CSS_SELECTOR_HERE"
    data-instant-search-suggestions="6"
    data-instant-search-categories="6"
    data-instant-search-pages="6"
    data-instant-search-positioning="right">
</span>

The snippet references the Content configuration for the product logic, amount of products to return, the design etc and returns a full HTML block that is inserted into the snippet.
Some snippets require additional data like product-IDs or category ID which should be added.
By default, new Stores in Clerk come with our Best Practice already created as individual Content blocks, making it easy to get started.

Other options #

For an extensive rundown of our technical platform, including integrating with the API directly, check this article

There are some cases where a serverside API integration is better for you, for example when:

Replacing an existing API with Clerk
Managing complex pricing rules and customer catalogues
Building an app

If these do not apply to you, we recommend using Clerk.js.

Multiple domains #

This way, you can separate products, sales, currencies etc. to keep track of each language.

Start by creating your main Store and follow the Setup Guide to connect your Store to Clerk.io, and choose the Recommendations and/or Search Results you that you want to display on your webshop.
When you are done with the initial setup, go back to the start page of my.clerk.io (by clicking the Clerk.io logo in the upper left side corner of the side-menu) and then click "+ Add new store" the last option of the scroll down list (generally under your existing store(s) and your company name):