Single-page apps #
When a page is loaded the first time, the Clerk.js library automatically fires a function to render all Content blocks on that page.
However, for single-page apps using frameworks like vue.js or next.js, pages are rendered with javascript rather than a standard page load.
Due to this, you need to control the rendering with Clerk.js to match how you load pages in the single-page app.
Include Clerk.js #
Clerk.js only needs to be loaded once, when the site is initially loaded. After this, the library will be availble throughout the session. Include it just before the </head> in your HTML:
<!-- 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_PUBLIC_API_KEY'
});
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
Control rendering #
This is done with the function Clerk("content", "#ID")
Every time a page is loaded, do these steps in order:
- Add the Clerk snippet to the HTML. Make sure it has a unique ID you can target
- Run
Clerk("content", "#ID")to render it
When the visitor leaves the page, destroy the snippet, to ensure you can render it again if the visitor returns to the same page. This is to ensure Clerk.js does not see the snippet as previously rendered, causing it to not visualise.
Example:
<span
id="clerk-custom-snippet"
data-template="@home-page-visitor-recommendations">
</span>
<script>
Clerk("content", "#clerk-custom-snippet")
</script>
For more info check our documentation for Dynamic Content here
Impact on Pagespeed #
If you use Google Page Speed Insights to analyse your site’s performance (as you should - or at least an equivalent tool) you will see Clerk.js listed under Leverage browser caching. This article will tell you why this is a good thing.
The purpose of Clerk.js is to make it super simple to insert results from Clerk.io into any website. Clerk.js contains a bunch of features to handle tracking and UI components such as search-as-you-type, sliders, exit-intent popups.
When we add new UI features or make improvements to existing ones, they are included in Clerk.js and must be downloaded by the end user in order to use them.
Having a cache expiry of 60 minutes means that when we release new features they will be available to everyone within a maximum of 60 minutes. The longer the cache time the longer before everyone has access to the newest features.
The important thing is that end users only have to download Clerk.js once when new features are available!
The 60 minute cache expiry just means that the end users browser will check in with Clerk.io every 60 minutes. If no changes have been made to Clerk.js nothing will be downloaded. This check-in request is both super fast and cheap since data will only be downloaded if a new version of Clerk.js is available.
The cache expiry time of 60 minutes is thus a tradeoff between minimising web requests and seeping new features and improvements. Remember that most sessions are way lower than 60 minutes and thus the request will only be made once per session or visit.
As you can see in the screenshot this is a normal practice that (as well as Clerk.io) is used by Google, Google Analytics, Facebook, New Relic, Trustpilot and many others.
Making API calls #
You can use Clerk.js to make API calls, by using the built in function Clerk.call(), this function takes 3 arguments.
Example Call #
Define the function, and call it in the tracking-script.
HTML
<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);
Clerk('config', {
key: 'INSERT_YOUR_API_KEY_HERE'
});
</script>
<script>
function popularProducts(){
Clerk("call",
"recommendations/popular",
{
limit: 10,
labels:["Home Page / Bestsellers"]
},
function(response){
console.log(response);
},
function(response){
console.error(response);
}
);
}
</script>
Response #
The response to a JavaScript Object, with the status of the API call, and the result.
JavaScript
__clerk_cb_1(
{
"status":"ok",
"count":72,
"facets":null,
"result":[399,410,551,338,403,439,425,402,406,456]
}
);
Working with the response #
Use a Callback function to handle the response
HTML
<script>
Clerk("call",
(
"search/categories",
{
'query': "men",
'limit': "10"
},
function(x){
var cat = x.categories;
if(cat.length > 0)
{
let heading = document.createElement('h3');
heading.textContent = 'Related Categories';
document.querySelector('#your-target').append(heading);
}
for(var index in cat) {
var clerkName = cat[index].name;
var clerkUrl = cat[index].url;
let link = document.createElement('a');
link.href = clerkUrl;
link.textContent = clerkName;
document.querySelector('#your-target').append(link);
}
}
)
</script>
This example will return the categories matching the query, and present them as text. This way you can make calls to our API quick and easy.
Common console errors #
When setting up Clerk.io you might run into problems, for a number of different reasons.
The most common problem is that you have installed Clerk.io, but products are still not being shown.
This article shows you the messages that Clerk.io shows in the console and explains how to deal with them to help you when debugging.
If Clerk.io encounters an error, and we know what the error is, you will see a message in your console:
By clicking the error link you will get more information about what went wrong, which you can use to debug the error yourself, or to send to our support team who will help you out.
These are the most common errors from the console:
“LogicalError: Unknown content ‘insert-name’” #
This error will show if the embedcode you inserted is referencing a Website Content that does not exist, in data-template.
To fix it, make sure that the name in the embedcode matches a Website Content.
You can always click Edit Content for any Content, to see what the embedcode should be:
“AuthenticationError: Invalid API endpoint” #
This error normally happens if you have used the class “clerk” in your HTML somewhere:
The class “clerk” is reserved for use with our embedcodes, as its used to handle the calls to our server.
To fix it, make sure that you name the class something else, for example “clerk-product” or similar.
“ParsingError: Invalid type of argument product” #
This error means that the ID supplied for a product in the embedcode, has a wrong type or syntax.
For example, if your product-ID’s are integers they also need to be so in the embedcode. Further, its important to remember the brackets around the ID, as it needs to be a list:
<span class="clerk" data-template="@product-page" data-products="[123]"></span>
“ParsingError: Invalid type of argument category” #
As with the above, this means that the ID supplied for a category is wrong.
In most cases, it happens if the placeholder in the category embedcode has not been replaced by an actual ID:
<span class="clerk" data-template="@category-page" data-category="INSERT_CATEGORY_ID"></span>
The output of the code should contain the ID of the category, like so:
<span class="clerk" data-template="@category-page" data-category="257"></span>
To fix this, select your shop system in the drop down menu in Edit content->Insert into website before copying the embed code:
The embed code will then change to include your platforms logic to select the correct category ID:
In custom setups you will however need to set your own logic in the embed code.
“AuthenticationError: Incorrect public API key” #
This error will show if the public API key you have provided, does not match any account in Clerk.io:
To fix this, first login to my.clerk.io, and go to Settings -> API Keys
Here you can check the Public API Key and make sure that this is the key you have used in your Clerk.io tracking script
Converting designs for Clerk.js 2 #
Since Clerk.js 2 uses the more flexible template language Liquid, you need to convert the Designs into this language.
1. Start by going to my.clerk.io -> Recommendations / Search -> Designs and click New Design:
2. Select the design type, the type of content and Name the design (we recommend adding " V2" so its obvious that you are using Clerk.js2). Then click Create Design.
3. Choose as Template the Product Slider (HTML) for the Recommendations, if you are working on the Search designs you will have to pick Instant Search Dropdown (HTML) or Search Page (HTML).
4. When you are done, click Create Design
5. This will give you the HTML and CSS code that you can manually overwrite:
6. Go back to Recommendations / Search -> Designs and click Edit Design for your old Clerk.js 1 Design.
7. Now you need to copy over the old Clerk.js 1 Design to your new Clerk.js 2 Design. You will notice that there is no Container Code in your new one. This is because Liquid uses for loops to render all the products. Copy your old Product HTML inside the for-loop, and you old Container Code around it:
8. Lastly, copy over your CSS as well:
9. Now you need to convert the Design into Liquids syntax. The main difference is that the old Designs used the syntax
{% raw %} {{ formatter attribute }} {% endraw %}
while v2’s syntax is
{% raw %} {{ product.attribute \| formatter }} {% endraw %}
10. Go through all of your attributes and change them to the new format:
11. If you are using {% raw %} {{#if}} or {{#is}} {% endraw %} statements, these need to be converted as well, to the syntax {% raw %} {% if product.attribute %} {% endraw %} Do something {% raw %} {%else%} {% endraw %} Do something else {% raw %} {% endif %} {% endraw %}:
12. Now click Update Design to save the changes.
13. Lastly, go to Recommendations / Search -> Content and change your Clerk.io Content to use your new Design.
14. Click Update Content. 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.
