HomeEngagementContentDiscoveryOther resources
Guides

Experiments for developers

Suggest Edits

This part of the documentation is aimed at front-end developers using Experiments. If you are not a developer, please take a look at our Experiments documentation. If you know HTML / CSS / Javascript and you would like to maximize the use of Experiments, you have come to the right place!

❗️

Advanced topic

You should take a look at the behind-the-scenes of Experiments documentation first to make sure that the explanations and use-cases on this page make sense. Also make sure that you are familiar with the rest of the documentation for Experiments, primarily the main Experiments documentation.

This is an advanced documentation aimed at front-end developers who understand HTML, CSS, Javascript, and the DOM of a webpage.

Custom CSS selector

Every experiment modification begins with the element selector. While selecting elements on the webpage in the Experiments editor, the editor does its best to automatically generate a CSS selector that only matches the selected elements. However, you can write your own CSS selector! Just click in the middle of the top bar of the Experiments editor to edit the CSS selector, enter you own selector and press ENTER.

  • If you want to modify only a few specific elements on your website, give them a unique ID in your website's HTML and then use this ID to write custom selectors for modifications to ensure that they do not match any other elements.
  • Conversely, if you want to create a more generalized modification (like changing the color of all links on the page), just select all elements by their class or HTML tag name (type a or .link and press ENTER, then you can choose the Change modification and select a different color, for instance).
  • You can use the body selector to perform some global modifications or insert global content. For example, you can insert global scripts or insert global styling this way (read more below). Since there is always just one <body> element on the page, this is the perfect way to perform one-time global modifications.
  • Additionally, you can even use the head selector to select the <head> element. You can use this to insert content in the head, like meta tags and external style links. This offers a lot of flexibility. It should also be possible to write a selector to match some of your existing elements in the head, let's say the <title> element, and modify its content or attributes, or you can select an existing <link rel="stylesheet" src="..."> element and change its URL! Just be careful and test your changes before deploying them live.

Inserting global content

Using the knowledge from the previous section, you can use either the head or the body selector to insert global content into the webpage, usable from your other scripts or other modifications in the experiment.

Script

Type in the body selector, press ENTER, and select the Run script modification. Choose the run mode called immediately, before the page content is loaded to run your script as soon as possible. Then you can type your Javascript code. For example, you can register global Javascript functions here and then use them later in other modifications of the experiment.

Style

Type in the head selector, press ENTER, and select Insert > HTML. For the placement, choose Put inside the element as the last child to insert content at the end of the <head> tag. Then, in the HTML, insert:

<style>
  /* global styles here */
</style>

📘

Please excuse the current suboptimal user experience when creating global content. We have plans how to improve the user interface of the Experiments editor to allow inserting global content into the webpage more easily.

Targeting criteria / experiment filters

Note that aside from the standard targeting filters for experiments like target devices, page URLs, or schedule (accessible in the Settings tab), you can also define a custom Javascript condition. This code is executed before the experiment is applied, it runs in the context of the webpage and you can use it to perform any other additional checks – like checking whether a cookie exists, running any of your custom functions or accessing the data layer. Read more in the documentation for the custom Javascript condition.

Modifications can change previous modifications

This might be obvious, but because the modifications are applied in the strict order they are defined in, you can modify content inserted in one modification in another modification coming after it. This is very useful for inserting placeholders for dynamic content (read more below).

Inserting dynamic or personalized content

You can use Experiments to insert personalized content for your customers or to insert dynamic content into the webpage. This is done using Jinja and it is supported almost everywhere in the experiment modifications (like in the HTML, in the values for visual changes, or in the Javascript code).

Have in mind that using Jinja in a modification makes it "personalized", which means that the modification will always be loaded asynchronously (read more about that in How Experiments work behind the scenes). A common approach to avoid content flickering in this case is to have two modifications:

  1. The first one inserts a simple static HTML placeholder content in your webpage. For example, if you want to insert recommendations for the customer, you can insert an empty <div> tag with a distinct ID, proper styling, constant height, and a placeholder text, such as Loading recommendations.... You can even set up some CSS transitions here for a better user experience. This modification is static, so it gets inserted into the webpage content immediately without flickering.
  2. The second one replaces the HTML content of the <div> inserted in the first modification with the dynamic recommendations content. You can even make this dynamic content hidden by some CSS first (so it does not suddenly pop on the screen), and then use a third Run script modification which reveals the content over time (either using Javascript or CSS transitions)!

Experiments for SPA

Reload experiments

You might be interested in achieving non-flickering experiments on single-page applications in Bloomreach Engagement.

Our SDK team developed a function to trigger a reload of experiments to overcome the problem of changing URLs without a hard refresh, which is typical for SPA.

To call the function, make sure you have a non-flickering mode set up on your site (both sync and async modes are supported). With the non-flickering setup, you will then be able to call the function: webxpClient.reset().

There are several ways to trigger this function, either directly in your website code or in a tag manager you might be using.

This function can also be generated via BrE Tag Manager. Make sure that you have the default setting for spa_reloading.tags in the configuration:

You can then use the tag containing the function mentioned above, which fires on all pages integrated with our SDK. Any URL change made on your website will trigger the fetching of our experiments from the backend, and they will be applied automatically.

Retrigger run script modifications

If you are using data layer events to trigger experiments in a single-page application, you can configure run script modifications to execute each time the trigger event occurs.

  1. Make sure the experiment's Display setting is Always.
  2. Configure either of the following execute options for each run script modification in the experiment:
    • whenever a triggering event occurs (repeatedly)
    • repeatedly for each matched element

Updated about 2 months ago