Custom code

5 min

Optimizely Web Experimentation

Optimizely Personalization

Optimizely Performance Edge

Optimizely Web Experimentation and Optimizely Performance Edge let you use custom JavaScript or CSS code to make changes to your site and extend your testing capabilities beyond Optimizely's standard toolkit. With custom code, you can:

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

Use CSS selectors to change multiple similar elements simultaneously instead of making individual changes.

Load an external JavaScript file as part of a variation, such as to add an Olark or ClickDesk widget. You cannot 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 executes your custom JavaScript by appending it as a <script> tag to the body of your page.

Variation-level code and experiment-level (shared) code

You can apply custom code to a variation or apply it to an experimentcustom code to a variation or apply it to an experiment across all variations (including the original). Common use cases for experiment-level JavaScript code include:

Sending Optimizely Experimentation information to your analytics serviceanalytics service.

Adding API calls for custom eventscustom events.

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

See shared codeshared code to learn more about applying custom code to an entire experiment.

Add custom code to a variation

Add custom code to a variation with the step-by-step instructions below:

Go to Experiments and select the name of the experiment.

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

Click the Variation Code Editor icon. 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.

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

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

Custom code timing: synchronous and asynchronous

Synchronous timing – Includes the custom code in the snippet, applying the change before the page is visible. Use for lighter changes that need to run right away without flashing, like a headline swap.

Asynchronous timing – Download changes after the snippet, applying the change while the page loads. Use for heavier changes where a delay is not noticeable, like a popup or a section below the fold.

Change a custom code's timing with the steps below:

Open the Variation Code Editor.

Select the Synchronous Timing drop-down list.

Select the timing you want.

Click the Save & Apply button.

Custom code in Optimizely Web Experimentation and Optimizely Performance Edge

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

Custom code runs immediately. Your code runs 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. Your visual changes are not instantly translated to code. Instead, Optimizely stores the entire structure of what you change in the Visual Editor and lists a summary of those changes. These changes do not appear in the custom code box as they did before.

There is no jQuery dependency. If you do not need jQuery for your custom code (in variation code, experiment code or project code), you can remove jQuery from the Optimizely Web Experimentation snippetremove jQuery from the Optimizely Web Experimentation snippet.

Utility functions are available. See the developer documentation. In Optimizely Web Experimentation, optimizely.get(‘utils’) provides access to utilities like waitForElement, observeSelector poll, and waitUntil. See API functionsAPI functions for information. In Optimizely Performance Edge, window.optimizelyEdge.get('utils') contains a reduced set of utilities. See the Optimizely Performance Edge API referenceOptimizely Performance Edge API reference.

You can add your own jQuery. See jQuery and the $ variablejQuery and the $ variable to learn more. For more information about custom code, see the developer documentation.

Warning

The following code does not work in Optimizely Personalization because the body element does not exist at the time when the code runs (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’);
});

Use the custom CSS option to make changes to your variation without worrying about timing. These CSS changes are applied by appending a <style> tag to the end of the <head> tag, which is more efficient than making style changes than JavaScript or jQueryjQuery.

Note

Since there is no jQuery dependency in Optimizely Web Experimentation, you can remove jQuery from the Optimizely Web Experimentation snippetremove jQuery from the Optimizely Web Experimentation snippet if you do not need it for your custom code.