clerk.io

Manually installing elements #

WooCommerce is built around themes, which often means that the Clerk.io plugin cannot insert our embedcodes, because the hooks are not placed where they are supposed to.

This guide explains how to manually insert codes if that is the case.

1. Find the right file #

1. Start by locating your search-form. You can do this by checking your source-code, and finding a unique text for the field.

2. After identifying this, you need a good way of searching through your files to find this. We recommend using Sublime Text.

3. Open your webshops FTP files and locate public_html -> wp-content -> themes

4. Drag the themes to your desktop, to copy it to your computer. This will allow you to search in the files:

5. In Sublime go to Project -> Add Folder to Project

6. Choose the themes folder that you saved on your computer.

7. Now you can search in the files, by going to Find -> Find in Files. You can even choose to only search in .php files which is normally the file-type used for theme-files in WooCommerce:

2. Making the link to the search-page work #

If you have already followed the guide for setting up search, and have created a page in WooCommerce for the Search Results, but your search-field is not linking correctly, this is what you need to do.

1. Start by looking at the webshop in your browser. We recommend using Chrome.

2. Locate any HTML that seems to be unique for the search-field. For example searchform:

3. Search for this in Sublime, to find a list of files that its in:

4. Find the matching file on FTP.

5. Now you can change the needed settings to have Clerk.io link to the correct page. The 3 things you need to change are:

The URL that the customer is linked to, often found in the
element, needs to be changed to match the name of the page you created in WooCommerce. This will often be “soegeresultater” or “search-results”
The “name” attribute of the input-field, that needs to be searchterm
The hidden input field with name=“post_type” needs to be commented out.

6. A search-form could look like this before changing it:

7. And should look like this after the change:

8. Now you should be linked to the search page when searching: www.mywebshop.com/soegeresultater?searchterm=test

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

wp-content->plugins->clerkio->includes->class-clerk-visitor-tracking.php

An example can be seen below. Please be aware this is 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 effectively 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:

https//USER:PASS@www.ewoksRus.com

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 WooCommerce plugin, 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@woocommerce.clerk.io

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 plugin is either:

Not installed at all
Deactivated due to an update
A cache causes the link to not be initialised
WooCommerce permalinks are set to Post name instead of Month and name

First make sure that you have installed the plugin correctly and that it is activated.

If you recently auto-updated the plugin, WooCommerce sometimes deactivates the plugin. If this has happened, simply go to Plugins > Clerk and click Activate to get it back again.

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

If it still doesn’t sync properly, go to Settings => Permalinks and change the Common Settings to Month and name and press Save:

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 was unable to specify which error happened.

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

An example of such an error could occur once you upgrade both WooCommerce and Klarna. In this instance, the problem is created by the ‘woocommerce-gateway-klarna’ plugin which does not upgrade.

If this happens to you go to woocommerce-gateway-klarna ->includes->variables-checkout.php .

Look for:

if ( ! is_admin() && ! empty( $klarna_country )) {

and change it to:

if ( ! is_admin() && ! empty( $klarna_country ) && WC()->session ) {

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.

520 Web Server Returned an Unknown Error #

Usually this error is returned from CloudFlare, and often happens because of a bottleneck in Woocommerce that causes issues with higher Page Sizes. To fix it, simply set your Page Size to 50, and run a new sync:

522 Server Error: Connection Timed Out #

This error usually happens if the server is too busy to respond, or if our importer is not allowed access to the server.

First, wait a few minutes and try syncing again, to see if the server was busy.

If it still does not work, make sure to whitelist the importers IP in your server configuration. The latest IP address can be found here.

Invalid response returned from the WooCommerce API #

This error usually happens, if WooCommerce’s Debugging has been activated. This is never a good idea to have activated on a live-setup because it slows down pages, and potentially shows error messages in the frontend.

The sync issue happens if WooCommerce encounters an error while generating the product-data for the import.

This can be solved by deactivating Debugging in wp-config.php by setting define(WP_DEBUG’, false).

This guide explains it in more detail:

https://docs.woocommerce.com/document/woocommerce-product-search/api/debugging/

And this guide explains an alternate workaround:

https://aristath.github.io/blog/wp-hide-php-errors

Errors will still be logged even when not in Debug Mode, but they will be logged to a file instead.

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. Choose Design Type and follow the design set up Wizzard.

1.3. 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.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.7. There! You are now ready to switch over to Clerk.js 2.

Step 2: Upgrading your plugin #

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

Upgrading the Plugin can be done directly from the WooCommerce admin.

Start by going to Plugin->Add New

Then, search for Clerk in the search-field to the right, and click Update Now.

Thats it! Now you are running the latest version of Clerk.io for WooCommerce and Clerk.js 2 is running on your webshop!

If you already have the latest version, this button will simply say Active.

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

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

Links pointing to backend #

Every now and then, Wordpress / Woocommerce plugins mess up with the Wordpress rewrite rule.

The rewrite rule is the set of configurations that makes sure that links like this

domain.com/?p=123

becomes beautiful and SEO-optimised links like

domain.com/product/my-beautiful-product/

and are actually reachable by you and your customers.

If your links do not work properly, do this:

1. Log in your Wordpress backend

2. Then go to: Dashboard –> Settings –> Permalink

3. Scroll down and clic on the “Save changes” button at the bottom of the page without changing anything. That will overwrite the Wordpress rewrite rule.

4. Once the page has refreshed, empty your Wordpress cache (if any) then wait a few minutes. You should be able to see all your website pages again.

If after all of that you still cannot visit your website pages, get in touch with us at support@clerk.io , we’re here to help!

Warnings shown in backend and frontend #

The sync issue happens if WooCommerce encounters an error while generating the product-data for the import.

This can be solved by deactivating Debug Mode either through the plugin or directly in the WooCommerce files.

Handling require.js #

This guide only applies when using up to v.1.7.1 of the WooCommerce 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:

wp-content -> plugins -> clerkio -> includes -> class-clerk-visitor-tracking.php

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:

Using the Plugin

If you are using Clerk.io’s v2.2.4or later, Debugging can be disabled directly from the Plugin page in your WooCommerce backend.

Go to Clerk -> Clerk Settings -> Debug Guide and click Disable Debug Mode:

Or Directly in the Files

Debug Mode can also be deactivated through FTP, in wp-config.php by setting define(WP_DEBUG’, false).