Clerk.io Developer Documentation
API ReferenceHelp ArticlesService StatusProduct UpdatesLog In

Configuration

How to use Clerk.js to smoothly integrate Clerk.io onto any website frontend.

Suggest Edits

🚧

Clerk.js v1 is despricated

Critical bugfixes will be maintained but feature development will only be done in Clerk.js v2.

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
  window.clerkAsyncInit = function() {
      Clerk.config({
          key: 'YOUR-STORE-API-KEY-GOES-HERE',
          collect_email: true
      });
  };

  (function(){
      var e = document.createElement('script');
      e.type='text/javascript'; e.async = true;
      e.src = document.location.protocol +
      '//api.clerk.io/static/clerk.js';
      var s = document.getElementsByTagName('script')[0];
      s.parentNode.insertBefore(e, s);
  })();      
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Clerk.js is build to make integration of Clerk.io onto any store frontend fast and enjoyable for developers. Clerk.js does all the heavy lifting, such as making network requests, gracefully handling errors, rendering into the DOM and applying click and behavioural tracking out of the box.

By default, Clerk.js should be embedded into every page of the store just before the end of the body. You can get your tracking code at my.clerk.io under Integration.

When loaded, Clerk.js will be exposed as the global Clerk object.

Configuring Clerk.js

📘

Clerk.js is configured by default

If you use one of your plugins, or copy-paste the tracking code from my.clerk.io, Clerk.js is already configured.

This is only for if you need more advanced customisation.

Clerk.js is configured in the Clerk.config method. This method takes a single object with the configuration.

Here are the configuration options:

Option

Purpose

key

Your store's public API key.

visitor

The visitor's visitor id. This will be auto-generated by default.

timeout

Global timeout for API requests in milliseconds. Default is no timeout.

language

Global configuration of the language to be used if applying multiple languages. This will be auto detected by default from the page's language meta information.

collect_email

true if Clerk.js should automatically detect emails from input fields, else false. This is used for ie. abandoned basket and other personalised emails. falseby default.

templateFormatters

A mapping of custom template formatters.

errorHandler

A global error handler function. Works just like the other event handlers.

Clerk.config({
  key: 'store_api_key',
  templateFormatters: {
    format_price: function(price) {
      return price.toFixed(2).toString();
    }
  }
});

Clerk.config({
  key: 'store_api_key'
});

Clerk.config({
  key: 'store_api_ley',
  visitor: '12345678asdfghj'
  timeout: 1000,
  language: 'english',
  collect_email: true
});

Clerk.config({
  key: 'store_api_key',
  errorHandler: function(event) {
    console.log(event.api, event.args, event.response);
  }
});

Clerk.js Methods

Clerk.js exposes some other low-level utility methods.

Method

Function

Clerk.config(config)

Configures the Clerk object with the configuration object config.

Clerk.renderBlocks(css_selector)

Takes a CSS selector and renders Clerk blocks that matches that selector.

By default, Clerk.js always calls Clerk.renderBlocks('.clerk') when loaded.

Clerk.addClickTracking(css_selector)

Add click tracking to all matching elements if they have a data-product-id attribute containing a product id.

Clerk.call(api, args, callback)

Low level function to call the Clerk.io API. api is the API endpoint, args is an object of the request parameters, and callback is a call back function taking the response object as its single argument.

Updated almost 2 years ago