FAQ

FAQ

Handling currency conversion #

From v3.0.3 of the Magento 1 extension, Currency Conversion is included by default, if you are using Magento 1’s standard conversion function.

Its added in my.clerk.io -> Designs, with the formatter price_in_currency.

The helper can be added to your Design in the following way:

{%raw%}
<div class="clerk-product-price">
{{ product.price_final_excl_tax | price_in_currency }}
</div>{%endraw%}

The helper will automatically convert the price to the currency of the current session, and add the currency symbol.

Example output:

Using formatters in designs #

Clerk.js allows you to write custom javascript functions, that adds new functionality to the Designs.

Formatters can be added in two ways:

  • Through my.clerk.io > Settings > Formatters, where each Formatter can be created as separate entries.
  • As a configuration for Clerk.js, in the tracking-script that is inserted on all pages, where multiple formatters can be added at once.

For Magento 1 this file contains the tracking-script:

app->design->frontend->base->default->template->clerk->tracking.phtml

An example can be seen below. Please be aware this is for Clerk V2 (latest version):

<!-- 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: 'O7UITkJIXqXibeQF9ONobiGGKYYKtbvh',
      formatters: {
                form_key: function () {
                    return '<?php echo $this->getFormKey(); ?>';
                },
                price_in_currency: function(price) {
                    price =  Math.round(price * 100) / 100;
                    var price_converted = Math.round((price * <?php echo (float)$rates[$currentCurrencyCode]; ?>) * 100) / 100;
                    var retVal = <?php echo json_encode($currentCurrencySymbol); ?> + ' ' + price_converted.toFixed(2).toString();

                    return retVal;
                },
                log_price: function(price) {
                   console.log(price);
                }
            }
        });
    };
    (function(){
  </script>

    <!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

You can write any number of Formatters, separated by comma:

formatters: {
   log_price: function(price) {
      console.log(price);
   },
   calculate_discount: function(price,special_price) {
      return price-special_price;
   },
   substring: function(text) {
      var short_string = text.substring(0,20);
      return short_string;
   }
}

After creating your Formatters, you can use them in your Designs using this syntax:

{%raw%}{{ x  formatter | attribute }} {{ x | formatter | attribute1 | attribute2 }}{%endraw%}

This allows you to create any functionality in your Designs that you require.

Syncing with HTTP Auth #

Often HTTP authentication is used on staging sites to avoid uninvited visitors.

This will block the Clerk Importer as well and display a 401 Unauthorized error in the sync log.

You can easily verify the importer by inserting the authentication info in the Import URL like below, in Data Sync at my.clerk.io:

http//USER:PASS@magento.clerk.io/clerk/api/store/1:

Common sync issues #

Note: We advice you to always update the extension to the latest version in order to get all up to date features from Clerk.
When importing data with the Magento 1 extension, the webshops server is responsible for sending the product- category- and sales-data to Clerk.io.

However in some cases, the servers configuration might stop the Importer from getting access, causing an error in Data Sync.

Below is a list of the most common errors and how to fix them.

401 Server Error: Unauthorized #

This error happens if your webshop/dev environment requires HTTP authentication to access it.

This is solved simply by inserting the Username and Password as part of the Import URL:

http://username:password@magento.clerk.io/clerk/api/store/1

403 Server Error: Forbidden #

This error happens if your server blocks the importer from accessing it. In most cases you simply need to whitelist the importers IP address to give it access.

The latest IP address can be found here.

Also check your public key, private key and import url are correct for the store you are operating within my.clerk.io

What if I have already whitelisted but the same error still occurs?

There are a few instances when you have whitelisted the importer’s IP address, and the error still persists, then we recommend you look into these parts:

  • The authentication part of the body may be removed from the request from the shop’s server.

  • Rate limit for the server in regards to cloudflares.

404 Server Error: Not Found #

This error happens if the importer could not access the link that sends us data from the webshop. In most cases it happens because the extension is either:

  • Not installed at all

  • A cache causes the link to not be initialised

First make sure that you have installed the extension correctly.

Second, be sure to clear your webshops cache before trying a new import.

429 Server Error: Too Many Requests #

This error happens if your server denies the importer access because of too many incoming requests.

You can fix this by setting the request limit higher, for your server or by setting Page Size to a higher value in the Clerk.io importer, causing the importer to make fewer, bigger requests:

If you are using the host provider Byte.nl, the importer usually returns this error because of their rate limiter. In this case, simply contact Byte.nl and ask them to whitelist the importers User-Agent " clerk".

500 Internal Server Error #

This error means that your server encountered an internal error and were not able to specify which error happened.

In these cases you can check your Server Log to identify which process crashed and why. In most cases its simply because of a product with an invalid attribute, or a function that is called wrongly in the webshop.

503 Server Error: Service Unavailable #

This error is usually temporary, and is caused by the server being too busy to handle the request. Try again a bit later.

If the issue continues to happen, it could mean that the server is overloaded with processes, and is close to maximum capacity.

Check the server load, to identify if this is the case.

Magento API: "" #

This error also means that your server encountered an internal error and were not able to specify which error or error code happened.

In these cases you can check your Server Log to identify which process crashed and why. In most cases its simply because of a product with an invalid attribute, or your memory limit was exceeded.

Add-basket-step not shown #

If the Add-To-Basket step is not activated its typically due to two reasons:

  • You have another add-to-basket popup or function enabled which blocks Clerk.io’s function

  • The wrong Content IDs are inserted in the extension.

Another add-to-basket popup is enabled

Start by checking your existing Magento installation, to see if you already have a popup or dropdown that is shown when adding a product to the basket.

These can normally stop Clerk.io’s add-to-basket step from showing.

If this is the case, deactivate it and try again.

Wrong Content IDs are inserted in Extension

If you have no other add-to-basket popup, and your powerstep is activated but not showing, its likely because the wrong template ID*s have been inserted in the Clerk.io extensions settings. This will cause the Powerstep to fail.

To fix this, start by logging into your Magento admin and go to System->Configuration->Clerk->Settings

Then choose the correct Configuration Scope that matches your store.

Under Power step settings, check the Templates field.

This field should contain the correct ID’s separated by commas, if you use more than one.

To make sure your IDs are correct, log in to my.clerk.io.

Choose the correct Store and go to Recommendations/Search -> Content.

Click Edit Content for a slider that you want to show in the powerstep.

Check the last tab " Insert into website" and locate the embedcode.

The ID found in data-template is the ID you need copy to the Magento extension:

Click Save Config in the Magento extension, and the Powerstep should work afterwards.

If you have activated the powerstep popup and it still does not show when adding a product to the basket, the issue is often because of Cache.

1. Start by going to System => Cache and clear all Internal and Third Party Caches.

2. If it does not solve it, you are likely using Full Page cache, which only impacts the pages a visitor has already viewed in their session. Deactivating it will have a minimal impact on page speed.

3. The screenshot below shows exactly which one to deactivate:

Once you have deactivate the Full Page Cache, the Clerk popup should appear. If it does not, please contact the Clerk Support from the live-chat icon in the lower right corner, and we can help find a solution for your specific setup 😃

Frontpage sliders always show the same products #

Normally this only happens if embedcodes are inserted through Magentos CMS Pages in the backend, as the frontpage is cached:

Instead, your embedcodes should be inserted directly to the Frontpage files, through FTP:

Magento will not cache results when inserted like this.

Clerk is not showing images #

When Magento’s image cache is cleared, either manually or automatically, all image paths change.

This means that the image paths sent to Clerk.io, no longer work.

This can easily be fixed by doing this:

  1. Login to my.clerk.io

  2. Click the Store where images are missing

  3. Go to Data

  4. Click Start New Data Sync in the upper right corner

This will start a new full sync of your products, which causes Clerk.io to get the correct image paths.

In Clerk.io’s Magento extension v2.1.0 this issue is fixed, by automatically starting a Sync when the image cache is cleared.

If you are using an older version of the extension, we strongly recommend upgrading to the latest version.

Upgrading to Clerk.js 2 #

Clerk.js 2 is a faster and much more flexible version of our JavaScript library that makes installing Clerk.io on any webshop a breeze.

However, since the two versions work slightly differently, you need to follow these steps to successfully upgrade.

The two main differences in Clerk.js 2 is that the Designs in my.clerk.io use the Liquid templating language, but they can also easily be created using the Design Editor.

Converting Designs #

Since Clerk.js 2 has a different approach Designs, you need to create new ones.

You can create your Clerk.js 2 Designs in one of two ways:

1.1 Start by going to my.clerk.io -> Recommendations / Search -> Designs and click New Design:

1.2. Choose Your Design Type.

1.3. In the Design Editor, click any of the existing elements like the name, image, button, etc. to edit it, or select new elements to add to the Design to add more information about products.

1.4. Click Publish  when you are done, and go to Step 2 in the guide.

1.5. Lastly, go to Recommendations / Search -> Content and change your Clerk.io Content to use your new Design.

1.6. 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.

1.9. There! You are now ready to switch over to Clerk.js 2.

Upgrading your extension #

If you already have the latest version of the Clerk.io Magento extension you can skip this step.

You can download the latest extension from this link:

https://github.com/clerkio/clerk-magento/releases/latest

2.1. Save any changes to extension files

Before you attempt to upgrade, make sure you have either:

  • Saved the changed files locally on your FTP or

  • Made a backup of any changed files, that you can carry over to the new extension.

Usually, the files that most developers change, are Product.php and Productbase.php, which control product attributes.

These files are found here:

app->code->community->Clerk->Clerk->Model->Catalog->Product.php

app->code->community->Clerk->Clerk->Model->Catalog->Productbase.php

Deactivate and uninstall existing extension

Before attempting to upgrade, it is very important that you do this:

2.2.1. Deactivate the old extension in Magento’s System->Configuration->Clerk->Settings page. Simply set Enable to No and click Save Config.

2.2.2. Afterwards , uninstall it either through Magento Connect or by deleting the files

from FTP if you installed it directly here.

Otherwise, your Configuration page might stop functioning and neither extension will work afterward.

2.3. Install latest extension

Lastly, install the latest extension again, and move any files you have backed up, to your FTP server.

Your configuration should be saved, even when installing the new version. Check System->Configuration->Clerk to make sure that everything is still there.

Now you have the latest version of Clerk.io for Magento installed, and Clerk.js 2 is running on your webshop!

The full documentation for Clerk.js 2 can be found here:

https://docs.clerk.io/docs/clerkjs-quick-start

Handling require.js #

This only applies when using v.3.7.2 or lower of the Magento 1 Clerk extension.

In some setups, Require.js stops Clerk.js from loading, which means that no sliders or search results will be shown.

When this happens, the following error will be shown in your console:

Uncaught ReferenceError: Clerk is not defined

There are two ways to handle Require.js. Both approaches require you to make changes to the tracking-script in this file:

app->design->frontend->base->default->template->clerk->tracking.phtml

Include “clerk” in Require.js #

The best approach is trying to get Require.js to recognize Clerk.io.

You can do this by inserting require([‘clerk’], function() {}); in the bottom of the tracking script:

Ignoring Require.js #

If the above solution doesn’t work, its possible to ignore Require.js.

You can do this by inserting window.__clerk_ignore_requirejs = true;

in the top of the tracking script:

After using one of these approaches, Require.js will now be compatible with Clerk.io.