Skip to main content
menu_icon.png

Everything you need to learn Optimizely X in one place: See our resource pages for Web Experimentation and Personalization.

x
Optimizely Knowledge Base

Custom code in Optimizely X Web

This article is about Optimizely X. 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

THIS ARTICLE WILL HELP YOU:
  • Decide whether your experiments can benefit from adding custom code
  • Distinguish between variation-level code and experiment-level (shared) code
  • Add custom code to your Optimizely X experiments 

Optimizely X allows you to use custom JavaScript or CSS code to make powerful changes to your site and extend your testing capabilities even beyond Optimizely's standard toolkit. With custom code, you can:

  • Execute your custom code only for visitors who are bucketed into a particular variation instead of for all visitors.

  • Use CSS selectors to change multiple similar elements at once instead of making individual changes.

  • Load an external JavaScript file as part of a variation, for example, to add an Olark or ClickDesk widget. You can't add code that includes a <script> tag using the Edit HTML feature in the Visual Editor, but you can paste external JavaScript into the <Edit Code> box. Optimizely X executes your custom JavaScript by appending it as a script tag to the body of your page.

Variation-level code vs. experiment-level (shared) code

You can apply custom code at the variation level, or you can apply it to an entire experiment, across all variations (including the original). Common use cases for experiment-level JavaScript code in Optimizely X include:

  • Sending Optimizely information to your analytics service.

  • Adding API calls for custom events.

  • Adding functions that can be used across multiple variations and calling them with different parameters in the variation code.

Check out our shared code article to learn more about applying custom code to an entire experiment.

Add custom code to a variation

Here's how to add custom code to a variation, with step-by-step instructions below:

  1. From the Experiments dashboard, click the name of the experiment.

  2. Select the variation you want to enhance with custom code. This opens the Editor.

  3. Click the Variation Code Editor icon (image03.png) in the top-right of the Editor window to begin adding custom code.

  4. The Variation Code Editor window opens to the JavaScript tab, where you can add custom JavaScript to the variation. Click the CSS tab to add custom CSS.

  5. Paste or type your code into the Variation Code Editor text box.

  6. Click Save & Apply (JavaScript) or Save (CSS) to save your custom code. To cancel your changes, click Revert to Saved instead.

Congratulations! You've successfully added custom code to a variation.

Custom code in Optimizely X vs. Optimizely Classic

Here are a few things to keep in mind about custom code in Optimizely X:

  • Custom code runs immediately. In Optimizely Classic, visual and code changes were mixed together, so Classic polled for each line separately and tried to run it when elements were ready. In Optimizely X, we removed this behavior so that your code runs exactly as written, often before the DOM is ready. This gives you as much control as possible over the timing of custom code execution. You can modify the timing by including code that specifies when things should run.

  • Custom code and visual changes are separated. If you've been using Optimizely Classic, you're probably used to the changes you make in the Visual Editor turning immediately into jQuery in the Edit Code box. For example, if you changed a headline’s text using the Visual Editor, you’d see code like $(‘h1’).text(‘New Headline’); in the Edit Code box.

    In Optimizely X, we’ve changed this behavior. The visual changes that you make aren’t instantly translated to code. Instead, we store the full structure of what you change in the Visual Editor and simply list a summary of those changes in the left sidebar. These changes do NOT show up in the custom code box the way they did before.

  • There is no jQuery dependency in Optimizely X. If you don’t need jQuery for your custom code (in variation code, experiment code or project code) you can remove jQuery from the Optimizely snippet.

  • Utility functions are available. Learn more in our developer documentation.

You can still add your own jQuery in Optimizely X. Check out this article to learn more about jQuery and the $ variable in Optimizely X. For more information about custom code, check out our developer documentation.

Because Optimizely Classic doesn't run custom code immediately (it waits for the specified element to be ready on the page), custom code you've used in Optimizely Classic may not work in Optimizely X Web Experimentation or Personalization.

For example, the following code won't work in Personalization because the body element doesn't exist at the time when the code runs (and remember, custom code runs immediately):

$(‘body’).css(‘background-color’, ‘red’);

To delay running the code until the whole page is loaded, use jQuery’s document.ready function:

$(document).ready(function() { 
$(‘body’).css(‘background-color’, ‘red’);
}); 

To make changes to your variation without worrying about timing, use the custom CSS option. These CSS changes are applied by appending a style tag to the end of the body tag, which more efficient than making style changes than JavaScript or jQuery.

Since there is no jQuery dependency in Optimizely X, you can remove jQuery from the Optimizely snippet if you don't need it for your custom code (in variation code, experiment code, or project code).