Clerk.js is a JavaScript library that simplifies the integration of our API with your frontend. There are three benefits to using Clerk.js:
- It’s robust, as it’s loaded asynchronously. This means that the rest of the page is not dependent on an API response before loading.
- It’s often faster, as your server can start rendering the page in parallel with Clerk.js making calls and rendering results.
- Visitor- and click-tracking is handled automatically for any results shown by Clerk. This requires no cookies, as we generate a hashed value of the visitor’s IP and useragent, combined with a unique store salt that rotates every 30 days.
Clerk.js is loaded with a lightweight tracking script added to the header of the website.
<!-- 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 -->
This script loads the library from our CDN and lets you access its functionalities through the " Clerk" object. The script configures Clerk.js with the API key so it already knows which Store it’s making API calls for.
When the page is loaded, Clerk.js scans it for any snippets with the class “clerk”.
It then uses the attributes from the snippet to build an API call while getting the API key from the config in the initialisation script.
<span
class="clerk"
data-api="recommendations/popular"
data-limit="10"
data-template="#clerk-product-template">
</span>
The visual representation is handled by the design, which is also referenced by the snippet.
Clerk.js uses Liquid designs, known from Shopify, to render HTML with the data returned by the API. These should be formatted as scripts, with an ID that you can reference in “data-template” of your snippet.
<span class="clerk"
data-api="search/search"
data-query="jedi"
data-limit="20"
data-template="#clerk-template">
</span>
<script type="text/x-template" id="clerk-template">
<h1>Search result for {{ query }}.</h1>
{% for product in products %}
<div class="product">
<h2>{{ product.name }}</h2>
<img src="{{ product.image }}" />
<a href="{{ product.url }}">Buy Now</a>
</div>
{% endfor %}
<a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Load More Results</a>
</script>
Snippets can also be simplified to only include a reference to a Content within my.clerk.io.
Designs are then handled with a visual editor or with Liquid HTML code just like in the frontend.
With this approach, most of the configuration is done in a user-friendly way from the admin panel. Your snippets will only need to contain the class “clerk”, any page-specific info like product ID’s, and a reference to the ID of a Content block in “data-template”.
<span class="clerk"
data-template="@product-page-alternatives"
data-products="[12352]">
</span>
