Skip to main content

Everything you need to switch from Optimizely Classic to X in one place: See the Optimizely X Web Transition Guide.

Optimizely Knowledge Base

Conditional activation for pages in Optimizely X

There are two versions of Optimizely
What version do you have?
Optimizely Classic
This is what the Optimizely Classic user interface looks like.
Optimizely X
This is what the Optimizely X user interface looks like.
. If you're using Optimizely Classic, check this article out instead.
relevant products:
  • Optimizely X Web Experimentation
  • Optimizely X Web Personalization
  • Optimizely X Web Recommendations

  • Activate an experiment conditionally, based on dynamically loaded content
  • Build experiments for single-page app frameworks like Angular, Backbone, Ember, or Knockout

By default, all Optimizely experiments are evaluated as soon as the Optimizely code snippet is loaded on the page. Once a visitor is bucketed into an experiment, the actual code to change any elements on the page will run as soon as those elements appear in the DOM. When your experiments are set up this way, we say they are in immediate activation mode.

There are times, however, when you may want to wait until a later point in time to activate your experiment. For example, if your page displays dynamically-loaded content, you may wish to activate an experiment after the page has loaded. You can do this by setting the experiment's activation mode to one of Optimizely's conditional modes: Polling, Callback, or Manual.

Why use conditional activation?

Generally speaking, you'd use a conditional activation mode when you want to wait to activate your experiment until certain conditions have been met, either in the page-loading process or in the user's journey through your site.

For example:

  • Your site is built on a single-page app framework (like Angular, Backbone, Ember, or Knockout), and you want to activate an experiment based on an event fired by that framework.

  • You’re testing a web application that re-renders (but doesn't re-load) the page when visitors perform certain actions.

  • Visitors will not be bucketed into an experiment until they take certain actions on a page, such as triggering a modal, scrolling to a certain point, or activating a widget.

  • You’re testing a multi-step form that appears in a modal and uses a “Next” button, but doesn’t load a new page.

  • You’re testing an e-commerce site and want to run an experiment that is only triggered when customers interact with the products in a particular way.

  • The page contains an AJAX request that executes long after the page has finished loading, and that AJAX request returns new content that must be modified.

Sometimes, when you make changes to an element, those changes appear correctly in the Editor, but are not visible when the experiment actually runs live. If this happens, it's an excellent sign that you should be using conditional or manual activation.

Here's what's going on:

  • When a visitor arrives at your experiment page, the Optimizely snippet executes immediately and tries to run the variation code. However, because the new element hasn't been triggered to appear, the selectors for this element do not exist yet on the page. 

  • Optimizely can't make changes to the element if the selectors can't be found on the page.

  • By the time a visitor clicks on the button to trigger the element, the Optimizely snippet has already finished executing and has stopped trying to find the selectors.

Conditional activation modes in Optimizely X

When you go to set the activation mode for your pages, you'll have four options to choose from. The first, Immediately, is the default activation mode in which Optimizely evaluates your experiment as soon as the snippet loads. This is not a type of conditional activation. The remaining three options, however, are all conditional activation modes:

Polling. Set your activation mode to Polling when your condition for evaluating the experiment is that a certain element is present within the page. This makes polling ideal for evaluating experiments that hinge on any type of delayed content. For example:

  • You're running an experiment on a product detail page where the category isn’t available in the URL, so instead you rely on keywords within the page as a sort of metatag. You'd use polling because those keywords live below the <head> tag, and therefore load later.

  • You're running an experiment that targets something far down in the page - even as low as the footer -- where content is loaded later.

Optimizely polls every 50 ms for 2 seconds for this condition to evaluate as true, at which point the experiment will be activated. It will stop polling 2 seconds after DOM ready. If the condition does not evaluate to true before this point, the experiment will not activate and a callback should be used to activate the experiment.

Callback. Is your experiment designed to begin with an event, like a route change in a single-page app or the click of a particular button somewhere on your page? If so, you should set your page's activation mode to Callback. A callback listens for a specified event to be triggered before launching your experiment. For example: 

  • You want to show alternate versions of a form based on an event-driven action, like clicking a button elsewhere on the same page.

  • You want your experiment to activate when there is a route change within a single-page app.

  • You're running an experiment that targets a modal that doesn't load until the user actually clicks a button to open it.

You'd want to use a callback to activate experiments like these.

Manual. When you select Manual, you are telling Optimizely that the activation event will be controlled by code you place directly onto your site or within your app. See our developer site for more information on how to manually activate your pages.

Set conditional activation

In Optimizely X, activation modes are set at the page level. This differs from the way conditional activation was handled in Optimizely Classic; there, it was set at the experiment level. You can set a page's activation mode when you create it, or you can edit an existing page.

Select the activation mode you want from the dropdown menu. Immediately is the default. When this is set, Optimizely will evaluate the experiment as soon as the snippet is loaded in the page.

If you select Polling or Callback, you'll get a code window that looks like one of these:

If you select Manual, you'll get a code window (complete with sample code), just below a text box for entering the name of your API.

In these examples, note that Optimizely provides you with sample code only. You or your developer should replace it with custom code that will activate your experiment according to your specific requirements. If you don't, your experiment almost certainly won't behave the way you want it to. See our developer site for additional examples and use cases for polling, callback and manual activation.

To complete the process, click Save Page.

If you're using conditional activation for a multi-page experiment, make sure that the activation mode you choose will work for every page in the experiment. Otherwise, it will activate only on one page.

The activate API call and single-page apps

In Optimizely X, using the activate API call will restart Optimizely, and all campaigns or experiments on that page will then be evaluated. This has important ramifications for single-page apps (SPAs), because it is likely to affect how you go about setting up the page in the first place.

Imagine an experiment that activates on the second step of a SPA. It's tempting to assume that the user will get to step 2 by first going through step 1, and then tell Optimizely to look for a hash change; if a hash change occurs, then Optimizely would restart and evaluate the experiment. But if the user can get to step 2 - say, by following a bookmarked link - without first going through step 1, there will be no hash change to notice, and Optimizely will not know it's supposed to activate the experiment.

Instead, the solution is to set Optimizely to check for the presence of a string fragment within the URL that indicates the user is on step 2. Because it’s set to activate immediately, you can then enter the experiment directly from that point.

Conditional activation and jQuery

In Optimizely X, there’s been an effort to remove dependencies on jQuery. The blocks of sample code provided for polling and callback modes are in pure JavaScript instead.

This means you cannot copy jQuery code directly into those code boxes from Optimizely Classic experiments. You can add jQuery to your Optimizely X experiments by including the API call described in our developer documentation.