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

Single-page applications 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

  • Technical users: use Optimizely X with single-page applications built with frameworks like AngularJS, Backbone.js, Ember.js, React, or Meteor
  • Non-technical users: collaborate with your developer to write the code needed to use Optimizely X with single-page applications

Using Optimizely with a single-page application (SPA) generally requires a different approach from what you might be used to. This article will help you create Optimizely experiments in frameworks like AngularJS, Backbone.js, Ember.js, Meteor, or React, without much technical effort.

If you have questions, ideas, or suggestions about using these frameworks to create experiments in Optimizely, check out the Developer forum on Optiverse and share your thoughts with other like-minded Optimizely users.

You can also find code samples for using Optimizely with SPAs in our developer documentation.

Single-page apps vs traditional websites

With a traditional website, content is organized on individual pages. These pages are usually static: they don't change in response to a visitor's actions. Instead, when a visitor clicks a button or a link, the site usually serves a brand new page, with its own static content.

An SPA contains the same full range of content, but is built to be faster, more responsive, and more compact. SPAs do this by swapping out old content for new, without serving any new pages to visitors. The SPA and all its content is only loaded once, when the visitor first views the site, so there's no extra back-and-forth between the browser and the server. This reduces the amount of data that has to be transferred. It also gives visitors an experience that feels faster and easier.

Think of the page like a sheet of stationery with a letterhead. In a traditional website, each page would use a new sheet, even though the letterhead doesn't change, and this can quickly become wasteful. Now imagine that instead of writing directly on these sheets, you put all your content on sticky notes. You can add, remove, and rearrange these notes on the sheet in any configuration you want and in response to anything your visitors do, and you never need more than one sheet of stationery.

How Optimizely works with SPAs

Optimizely requires a different approach for SPAs because Optimizely's snippet (which is in your page's <head> tag) generally loads each time the page loads.

With a traditional website, that's fine, because pages are often loaded and re-loaded in response to a visitor's action. But this doesn't happen with SPAs. The snippet is only loaded once, and it's not reloaded when the visitor takes action. Because of that, Optimizely’s default activation mode won’t re-check for URL Targeting or Audiences, and Optimizely won’t load any new variation code. Even if you see the URL change, that does not mean the whole page will reload.

Instead, you can trigger your experiments on SPAs using either page-level conditional activation or navigation-based activation.

Working with a UI library like React or Vue? Here's more about how to use Optimizely with UI libraries.

Page-level conditional activation on SPAs

Traditionally, when you run an experiment, you identify the pages to target by their URL. But you can't do that with an SPA, since by definition it's a single page, and the snippet only loads once, when the page first loads. 

You can get around that by identifying the "states" of the page that you want to target instead. For example, maybe you only want your experiment to run after a visitor clicks a link and can view a particular block of content. You can use conditional activation to identify when this happens, then launch your experiment.

An SPA changes whenever the visitor takes any kind of action, like opening or collapsing a navigation section, clicking on a button, or scrolling past a certain point on the page. Usually, these changes come about through the addition or removal of certain HTML/CSS classes. The conditional activation feature allows you to prevent an experiment from running until a class is added or removed, or any other condition that you define is met.

After you’ve identified the visual state of the page that you want to run your experiment on, you'll need to identify the corresponding behind-the-scenes code that defines the state.

For code samples you can reuse with Optimizely's three page-level conditional activation modes, see our developer documentation.

Navigation-based activation on SPAs

Because SPAs have only a single URL, you can't rely on the Optimizely snippet to reload whenever your visitors navigate to different parts of your SPA. However, you can still set up navigation-driven experiments. With Optimizely's navigation-based activation modes, you can effectively mimic the behavior of a more traditional website, and launch experiments when your visitors click on certain links or otherwise navigate to specific areas of your SPA.

To do this, you'll have to add a small amount of custom code to your Project JavaScript. This code initiates Optimizely's "activate" API call, which restarts Optimizely and forces it to evaluate all campaigns or experiments on that page.

Navigation-based activation works for SPAs that rely on either hash changes or HTML5's history API for navigation. 

For code samples to reuse with Optimizely's navigation-based activation modes, see our developer documentation.