The Clerk.io Developer Hub

Welcome to the Clerk.io developer hub.

This is site is only technical specification for developers.

You'll find comprehensive guides and documentation to help you start working with Clerk.io at our Help Center

Get Started    

Quick Start

How to quickly get started with Clerk.js.

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 behavioral tracking out of the box.

Installing Clerk.js

If you use an official Clerk.io extension or plugin this is done by default.

To install Clerk.js into any website just insert this code on every page just before the </head> tag.

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

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

Now just replace INSERT_YOUR_API_KEY_HERE with your stores API key and than Clerk.js is ready. You can find your store's specific embed code and API key under your store settings at my.clerk.io.

Embedding Clerk.io Results

The easiest way to explain how is just with an example.

The following code lists the store's 3 most popular products:

<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="3">

  <h1>{{ headline }}</h1>
  
  <ul class="product-list">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>
 
        <img src="{{ product.image }}" title="{{ product.name }}" />
 
        {% if product.price < product.list_price %}
          <div class="list-price">${{ product.list_price | money }}</div>
          <div class="price">${{ product.price | money }}</div>
          <div class="discount">You Save: {{ product.price / product.list_price * 100 | round }}%</div>
        {% else %}
        	<div class="price">${{ product.price | money }}</div>
        {% endif %}
        
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
</span>
<span
  class="clerk"

  data-api="recommendations/popular"
  data-limit="3">
	<!--
  <h1>{{ headline }}</h1>
  
  <ul class="product-list">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>
 
        <img src="{{ product.image }}" title="{{ product.name }}" />
 
        {% product.price < product.list_price %}
          <div class="list-price">${{ product.list_price | money }}</div>
          <div class="price">${{ product.price | money }}</div>
          <div class="discount">You Save: {{ 100 - (product.price / product.list_price * 100) | round }}%</div>
        {% else %}
        	<div class="price">${{ product.price | money }}</div>
        {% endif %}

        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
  -->
  <h1>Our Most Popular Products</h1>
  
  <ul class="product-list">
    <li class="product">
      <h2 class="product-name">Product Name #1</h2>
      
      <img src="/product/image/1.jpg" title="Product Name #1" />
      
      <div class="price">$59</div>
 
      <a href="/product/1">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #2</h2>
      
      <img src="/product/image/2.jpg" title="Product Name #2" />
      
      <div class="list-price">$495</div>
      <div class="price">$349</div>
      <div class="discount">You Save: 23%</div>
      
      <a href="/product/3">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #3</h2>
      
      <img src="/product/image/3.jpg" title="Product Name #3" />
      
      <div class="price">$149</div>
      
      <a href="/product/3">Buy Now</a>
    </li>
  </ul>
</span>

Let's break down how Clerk.js renders this embed code:

  1. Immediately after being loaded, Clerk.js will scan the page source for any element with the class clerk.
  2. Then it reads the data- attributes of the element and sends them as parameters to the Clerk.io API specified by data-api.
  3. When the API responds, the resulting products will be rendered using the template in the element body and be injected into the DOM where the element is placed.
  4. Then click-tracking is automatically added to each product to track sales impact.
  5. In case of an error, details will be logged to the browser's console.

Hosted Templates

Having templates, styling, and configuration embedded directly into the websites source code may be convenient for developers but not much for marketers. That's why our recommended integration is by using hosted templates via my.clerk.io.

Hosted templates work by first creating the Design under the Developers section and then using that for one or multiple pieces of Website Content under the Marketeers section of my.clerk.io.

The content can then just be embedded by the embed code given by the Content details page. It usually looks like this:

<span
  class="clerk"
  data-template="@template-content-id">
</span>
<span
  class="clerk"
  data-template="@template-content-id">
	<!--
  <h1>{{ headline }}</h1>
  
  <ul class="product-list">
    {% for product in products %}
      <li class="product">
        <h2 class="product-name">{{ product.name }}</h2>
 
        <img src="{{ product.image }}" title="{{ product.name }}" />
 
        <div class="price">{{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </li>
    {% endfor %}
  </ul>
  -->
  <h1>Our Most Popular Products</h1>
  
  <ul class="product-list">
    <li class="product">
      <h2 class="product-name">Product Name #1</h2>
      
      <img src="/product/image/1.jpg" title="Product Name #1" />
      
      <div class="price">$111,11</div>
      <a href="/product/1">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #2</h2>
      
      <img src="/product/image/2.jpg" title="Product Name #2" />
      
      <div class="price">$222,22</div>
      <a href="/product/3">Buy Now</a>
    </li>
    <li class="product">
      <h2 class="product-name">Product Name #3</h2>
      
      <img src="/product/image/3.jpg" title="Product Name #3" />
      
      <div class="price">$333,33</div>
      <a href="/product/3">Buy Now</a>
    </li>
  </ul>
</span>

Quick Start


How to quickly get started with Clerk.js.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.