HomeEngagementContentDiscoveryOther Resources

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:

3300


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.