Integrating and using experiments

Bloomreach provides multiple ways to integrate Experiments on your website. You can choose whichever best suits your needs. Each solution has its own benefits and drawbacks, and some solutions are harder to implement on your side.

How to choose

The specific integration that is used by our JavaScript SDK is selected with the new_experiments configuration option. Note that some solutions require further setup from you – keep reading.

Default basic integration

Used when new_experiments is set to false.

As of JavaScript SDK version v2.8.1 (December 2020), this is the default option. It is used when you use our Integration snippet as-is. This is our oldest and slowest provided solution for experiments.

This solution applies Experiments asynchronously. That means experiments start loading after your webpage has loaded. They are applied much later than the content is shown to the user (how much exactly often depends on the network). This is the simplest solution and it doesn't try to be smart. However, it can't avoid the Flickering effect, which means that your users would probably get a bad user experience, depending on your Experiments of course. Therefore, this solution isn't recommended.

Advantages

• No setup is required.
• Doesn't block rendering or hide your content.

Disadvantages

• This is the slowest approach.
• Suffers from the Flickering effect.

Asynchronous solution with hiding

Used when new_experiments is set to true or when new_experiments.mode is set to "async".

🚧

Important

This solution is not compatible with integrating through Google Tag Manager.

This solution also applies Experiments asynchronously. Unlike in the basic integration solution, here Experiments start loading as soon as your website starts loading. They don't block the website rendering. Instead, a CSS rule is used to hide your website until the Experiments are loaded and applied on the webpage.

This solution uses a CSS class specified in new_experiments.hide_class to hide the content of the webpage while the Experiments are loaded (read more in the integration configuration section). When you enable Use new experiments in the integration modal, a <style> tag is added to the integration snippet with CSS to hide the page content. You can customize the CSS in the <style> tag to suit your specific needs if you have the technical knowledge to do so, but the default implementation works very well already.

🚧

Important

If you are already integrated with Bloomreach using an integration snippet, you have to add the <style> part to the snippet on your website to use this Experiments solution. You also have to upgrade to the newest integration snippet (at least the snippet version v2.1.0).

You can also specify the maximum amount of time the webpage content is hidden. If this time runs out, the content is revealed even if your Experiments haven't been loaded yet (which might again result in "flickering"). The time limit is configured using new_experiments.timeout (again, read more in the integration configuration section) and defaults to 4 seconds.

🚧

Important

The asynchronous solution with hiding may still cause the flickering effect under certain conditions. Please refer to Flickering effect in Experiments - Limitations and workarounds for details.

Advantages

• Fast loading of experiments.
• Hides the page content until Experiments are loaded, therefore it prevents content "flickering".

Disadvantages

• This solution hides your webpage content using CSS, which might conflict with your existing setup in rare cases.
• Your users might see a blank white page in between page visits.

Synchronous solution with a service worker

Used when new_experiments.mode is set to "sync" and a service worker is set up.

🚧

Important

This solution is not compatible with integrating through Google Tag Manager.

This is the best and most sophisticated solution. It utilizes a synchronous script tag which blocks the rendering of the webpage until the Experiments are loaded. It also relies on a service worker to ensure that the script doesn't block the webpage for too long. Experiments start loading as soon as the webpage starts loading. The downsite is that some technical knowledge is required to use this solution.

The first prerequisite is to set up the service worker. The service worker is used to ensure that the blocking script request doesn't take longer than the configured time limit (so your whole webpage doesn't get blocked for a long period of time). The time limit is configured using new_experiments.timeout (read more in the integration configuration section) and defaults to 4 seconds. The service worker gets automatically registered on the first page visit.

If the service worker is unavailable during a page visit, this solution defaults to the Asynchronous solution described in the previous section. Therefore, you have to read through that section and perform the necessary setup for the Asynchronous mode, too (in particular, you have to set up the <style> tag in the snippet)!

🚧

Important

On the very first page visit, the service worker is never available because it is only registered after the page loads. Therefore, the first page visit will always use the Asynchronous solution and only use the Synchronous solution on the second and next page visits.

The synchronous solution with a service worker may still cause the flickering effect under certain conditions. Refer to Flickering effect in Experiments - Limitations and workarounds for details.

Advantages

• Fast loading of Experiments.
• Blocks the webpage from rendering and thus prevents content "flickering".
• Users don't see any blank white page between page views.

Disadvantages

• Technical knowledge is required to set up the service worker.
• Requires additional setup apart from using the integration snippet.

What's the difference between the asynchronous and the synchronous solution?

The main difference for you, as the website owner, is that the technical setup required for each solution differs. The Asynchronous solution is much easier to set up, whereas the Synchronous solution requires a bit of technical knowledge to set up the service worker.

From the user experience point of view, here's the main difference:

• With the Asynchronous solution, the user will see a blank white page when visiting a new page on your website. When they click on a link, they will see the old page, then the blank white page while the Experiments are loading, and finally the new page. When the blank page is visible, both Experiments and your page content load simultaneously.
• With the Synchronous solution, the user will only see the new page. When they click a link, they will see the old page, then the new page, without any blank pages. This works because the Experiments block the rendering of the page content, and the browser keeps displaying the old content until the new content is ready to be shown. The user will get a better user experience, but there is a small downside: your page content will only start loading after the experiments are downloaded.

Troubleshooting

Here are a few common problems you can encounter while integrating Experiments into your website. If you have problems with using the Experiments, see the troubleshooting section in Experiments.

Experiments are flickering

If you are using the basic integration, this is expected. Upgrade to the Asynchronous or the Synchronous solution.

If you are already using the Asynchronous or the Synchronous solution, there are multiple possibilities:

• Make sure that you have the <style> tag with the correct CSS to hide the page content in your integration snippet. Read more in section about Asynchronous solution.
• The integration snippet must be in your website's <head>. Read more in Integration.
• If you changed new_experiments.timeout, try increasing the number to allow more time for Experiments to load.
• Make sure that new_experiments.hide_class matches the CSS class in the <style> tag in your snippet.

Warning: A parser-blocking, cross-site script is invoked via document.write

When you are using the Synchronous solution, you will see a warning in the browser console like this:

This warning is expected and nothing to worry about. It occurs because the integration snippet uses document.write to write a synchronous (blocking) JavaScript script to the webpage to block the rendering until the Experiments are downloaded and loaded. Currently, the only way to do this in JavaScript is to use document.write which, unfortunately, always results in this warning. But don't worry, this solution is used only if the service worker is available (otherwise it switches to the Asynchronous mode). The service worker makes sure that the request doesn't take longer than the time limit configured by new_experiments.timeout (4 seconds by default) and therefore your website won't get blocked infinitely.

The warning also states that the request may be blocked by the browser due to poor network connectivity. If this happens, we'll automatically switch to the Asynchronous solution and deliver the Experiments asynchronously.

📘

Recommendations via experiments

If you are interested in deploying personalized recommendations via experiments using a predefined ready-to-use block, refer to our guide which will walk you through the setup.