Bloomreach Engagement provides multiple ways how 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 that Experiments start loading after your webpage has been 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 does not try to be smart. However, it cannot 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 is not recommended.

Advantages

• No setup is required
• Does not 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".

🚧

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.

🚧

If you are already integrated with Bloomreach Engagement 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 have not 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.

Advantages

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

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.

🚧

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 does not 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 does not take longer than the configured time limit (so your whole webpage does not 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 not available on 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)!

🚧

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.

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 simply 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 is different. 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 are loading at the same time.
• With the Synchronous solution, the user will only see the new page. When they click on a link, they will see the old page and then the new page without any blanks. This works because Experiments block the rendering of the page content and the browser will keep displaying the old page content until the new page content is ready to be shown. The user will get a better user experience but a small downside is that your page content will only start loading after 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. Please 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 side 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 does not 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 will 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, please refer to our guide which will walk you through the setup step-by-step.