FAQ

Changing image sizes #

Per default, the extension uses the original image sizes that are set in Magento 2 but these can be changed if needed.

Start by logging in to your Magento 2 backend and go to:

Stores -> Configuration ->Clerk ->Configuration

Under Synchronization-> Image type you can choose exactly which resolution to send images in:

Afterwards, click Save Config.

Now you simply need to run a new Sync in my.clerk.io and your new image sizes will be imported.

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 2, this file contains the tracking-script:

vendor->view->frontend->templates->tracking.phtml

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

    Clerk('config', {
      key: 'O7UITkJIXqXibeQF9ONobiGGKYYKtbvh',
      formatters: {
             log_price: function(price) {
             console.log(price);
          }
      });

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 %} {{{ price | log_price }} {{ price | calculate_discount |  special_price }}) {% 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@magento2.clerk.io/

Common sync issues #

Note: We advice you to always update the plugin to the latest version in order to get all up to date features from Clerk.

When importing data with Clerk.io’s Magento 2 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 import 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@magento2.clerk.io

403 Server Error: Forbidden #

This error often happens due to one of these reasons:

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

• You may have incorrect public key, private key and/or import url within the store in my.clerk.io

• You are using Storeviews with hidden URL’s, like mywebshop.com?__store=b2b. Sometimes, these URL’s can also contain 3 underscores like this: mywebshop.com?___store=b2b

If the latter, simply include the __store parameter in the URL in Data:

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 to look into these.

• 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 empty 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 hypernode.com/nl, the importer usually returns this error because of their rate limiter. In this case, simply contact hypernode.com/nl and ask them to whitelist the importers User-Agent " clerk".

500 Internal Server Error #

This error mean 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.

Invalid response received #

This error usually happens if your webshop is using a redirect system, to send customers to different domains.

For example, going to " https://mywebshop.com" might redirect to " https://mywebshop.com/it"

If this is the case, you simply need to use the full URL when importing in my.clerk.io:

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.

Step 1: 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. Use the intuitive Design Editor to create new Designs, as described in the following points.

• 2. Convert your old Designs. Follow this guide to see how to do it.

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

1.2 On the following screen, give your Design a Name (we recommend adding " V2" so its obvious that you are using Clerk.js2).

1.3. Choose Design Type.

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

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

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

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

Step 2: Upgrading your extension #

WARNING: Remember to take backups of any modified files, as they will be overwritten.

Upgrading the Magento 2 extension is done via commandline.

Its done by following these steps:

2.1. Login to your server through commandline.

2.2. Navgiate to your webroot folder (usually " /var/www/your_domain/public_html")

2.3. Enable Root Access by typing su and then enter your password.

2.4.Type in the following commands in order:composer update clerk/magento2php bin/magento setup:upgradephp bin/magento setup:di:compile

2.5. Wait for the extension to finish.

Your Magento 2 is now upgraded to the latest version.

Now you have the latest version of Clerk.io for Magento 2 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 guide only applies when using up to v.2.8.3 of the Magento 2 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

The Magento 2 extension already handles Require.js, but in some cases, its necessary to have it ignore Clerk.js.

You can do this in the following file:

vendor->clerk->magento2->templates->tracking.phtml

Simply insert  window.__clerk_ignore_requirejs = true;

in the top of the tracking script:

After using this approach, Require.js will now be compatible with Clerk.io.