Implement the one-line JavaScript snippet

9 min

Optimizely Web Experimentation

Optimizely Personalization

If this is your first time using Optimizely Web Experimentation or Optimizely Personalization, add a small snippet of code (see Optimizely Web Experimentation JavaScript snippetOptimizely Web Experimentation JavaScript snippet) to the <head> tag of your site's code to start running experiments. This snippet contains your unique project IDproject ID and lets Optimizely Web Experimentation or Optimizely Personalization run on your site. After you add it, the snippet updates automatically.

Note

If you are running your code server-side, you can prevent the snippet from auto-executing. See the Solutions section in the developer documentation on React server-side rendering and hydrationSolutions section in the developer documentation on React server-side rendering and hydration for information and steps you can take to reduce flickering.

After you complete the one-line implementation of the snippet with the following steps, you can run experiments or campaigns anywhere on your site.

Decide where to add the snippet

Consider the architecture of your site and experimentation program when deciding where to add the snippet. Each projectproject, or workspace, has its own snippet.

If your account includes cross-project eventscross-project events, you can track metrics across project spaces.

If your account does not include cross-project events, ensure that all parts of your site where you measure results are in the same project. One snippet should run across all those pages.

If you have separate development and production environments, or different domains and subdomains, you likely need separate projects (and snippets) for each.

Retrieve the snippet

Next, retrieve the snippet that you added to your site.

Go to Settings > Implementation.

Click Copy to Clipboard for the snippet you want to copy.

If your account uses custom snippetscustom snippets, you might see more than one snippet listed. Choose the one that is relevant to this part of your experimentation program.

Never use more than one snippet on your site at a time.

Note

If you ever need to find your project ID, it is the number immediately preceding the .js in the snippet URL.

Specify the origins where Web Experimentation or Personalization runs

Specify the domains where Optimizely Web Experimentation or Optimizely Personalization runs and track eventsruns and track events.

An origin is a combination of a specific hostname, protocol, and port on your site. Inform Optimizely Web Experimentation or Optimizely Personalization, where you track events. By default, events you track can only target changes on the same origin, enabling cross-origin targeting to track events across origins.

Add your snippet to the <head> tag of your site

For optimal performance, add the snippet to the <head> tag of the HTML for your site. You should implement the snippet as high up in the <head> tag as possible, generally after your <html> tag, charset declarations, and possibly other meta tags. Place the snippet before the code for analytics or heatmapping platforms.

Place these before the snippet:

Charset declarations and other meta tags, like <meta charset='utf-8'>.

jQuery, if you are using your own version and not Optimizely's version (see jQuery SettingsjQuery Settings).

Place the following after the snippet:

All other elements on your page.

Any analytics or heatmapping code.

Other content in a tag manager.

The following code sample is what the snippet might look like on a page:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <!-- Add other meta information here -->
        <!-- Add stylesheets here -->
        <script src="https://cdn.optimizely.com/js/12345678.js"></script>
        <!-- Add scripts and other content here -->
    </head>
    <body>

Why must I put the Optimizely snippet at the beginning of the <head> tag?

Optimizely Web Experimentation and Optimizely Personalization work by changing your page as the page loads. If the snippet is added to the top of the <head> tag, then Optimizely changes the page as it loads.

If the snippet is added anywhere lower, the code works, but if the page has already loaded content that the visitor sees before the Optimizely Web Experimentation snippet loads, the original version of the page may load before being transformed into the variation or personalization. This is known as page flashing. In most cases, the code executes too quickly for this to be visible. To avoid potential problems, add the snippet as early in the execution path as possible.

Warning

Do not modify the snippet. Copy and paste it onto your site exactly as you see it within Optimizely Web Experimentation or Optimizely Personalization. Otherwise, Optimizely may not run correctly on your site.

For example, do not add an id="optimizely" attribute to the script.

You need the ability to add the snippet to the <head> tag of your production environment and development environments (if you have both).

Note

The snippet is loaded synchronously by default, which is recommended. However, if you need to load Optimizely Web Experimentation asynchronously, see Synchronous and asynchronous snippet loadingSynchronous and asynchronous snippet loading.

Check that the snippet is implemented

Here is how to check that the snippet was implemented on your page correctly.

Load Optimizely Web Experimentation with a tag manager or into a CMS

Important

You should not load the Optimizely Web Experimentation snippet through a tag manager. If you must load Optimizely Web Experimentation through a tag manager, consider these pitfalls and implementation suggestionspitfalls and implementation suggestions , and contact your Customer Success Manager to discuss implications.

Loading Optimizely Web Experimentation through a tag manager can cause issues such as page flashing, where the original version of your page is briefly displayed to visitors before the Optimizely Web Experimentation experiment. Google Tag Manager, for example, does not support synchronous loading. Tag managers can also cause issues with your analytics integrations. To deliver the best experience to your visitors, you should implement Optimizely Web Experimentation outside of a tag manager.