Syntax

utils = window["optimizely"].get("utils");

Parameters

Parameter and Type	Child Attribute	Description
utils string	N/A	The argument indicating to get the utils object. Required.

Return value

Parameter and Type	Child Attribute	Description
UtilsObject	N/A	The utils object that contains a number of useful functions for developing experiences.
observeSelector function"optimizely"].get	Child attribute of type UtilsObject	Run a callback whenever an element changes.
poll functions = wi	Child attribute of type UtilsObject	A `setInterval` wrapper.
waitUntil functionindow["opti	Child attribute of type UtilsObject	Wait until the provided function returns true.
waitForElement function["optimizely"].g	Child attribute of type UtilsObject	Returns a Promise that is resolved with the first HTMLDomElement that matches the supplied selector.

Example Call

utils = window["optimizely"].get("utils");

Example Return Value

utils.waitForElement(selector);
utils.observeSelector(selector, callback, options);
utils.poll(callback, delay);
utils.waitUntil(conditionFn);

Description

Optimizely Web Experimentation uses some common functions to deliver experiences. You can also use those functions to write your own custom experiences.

waitForElement()

Returns a Promise that is resolved with the first HTMLDomElement that matches the supplied selector.

Syntax

utils.waitForElement(selector);

Parameters

Parameter and Type	Child Attribute	Description
selector string	N/A	A CSS selector indicating the element to wait for. Required.

Return value

Parameter and Type	Child Attribute	Description
Promise	N/A	An ES6-style Promise that will be resolved with the matching element.

Example Call

utils.waitForElement("h2");

Description

Returns a Promise that's resolved with the first HTMLDomElement that matches the supplied selector. This is commonly used to make adjustments to the element that you're waiting for when the promise is fulfilled.

Examples

Change the color of an element

Wait for an element to be loaded on the dom and change the color as soon as it has become available.

Example code for changing the color of an element

// Retrieve the utils library
var utils = window["optimizely"].get('utils');

// Wait for the footer element to appear in the DOM, then change the color
utils.waitForElement('.footer').then(function(footerElement) {
  footerElement.style.color = 'black';
});

observeSelector()

Run a callback whenever an element changes.

Syntax

utils.observeSelector(selector, callback, options);

Parameters

Parameter and Type	Child Attribute	Description
selector string	N/A	A CSS selector indicating the element to wait for. Required.
callback function	N/A	The function that will be executed when the element indicated by the selector changes. The first argument is the exact element that changed. Required.
options ObserverOptions	N/A	Timing configuration options. Required.
timeout integer or null	Child attribute of type ObserverOptions	Number of milliseconds or null. Default to null (i.e., no timeout).
once Boolean	Child attribute of type ObserverOptions	Only invoke the callback on the first match.
onTimeout function	Child attribute of type ObserverOptions	If timeout is specified and no elements match, execute timeout callback.

Return value

Parameter and Type	Child Attribute	Description
function	N/A	A function that can be executed to `unobserve` selector.

Example Call

utils.observeSelector(".productPrice", function(priceElement) {
  priceElement.style.fontSize = '30px';
  priceElement.style.color = 'red';
}, {
  "timeout": 6000,
  "once": true,
  "onTimeout": function() {
    console.log("Stopped observing");
  }
});

Description

This utility provides a subset of the functionality of a MutationObserver, allowing you to run a function whenever a DOM selector changes. Given a CSS selector and a callback, this function will invoke the supplied callback whenever a new element appears in the DOM matching the supplied selector.

poll()

A setInterval wrapper.

Syntax

utils.poll(callback, delay);

ParametParameter and Typeers

Parameter and Type	Child Attribute	Description
callback functionwindow["op	N/A	Function to be executed on the interval specified by `delay`. Required.
delay integer	N/A	Milliseconds to wait in between each callback invocation. Required.

Return value

Parameter and Type	Child Attribute	Description
function	N/A	Returns a function that cancels the polling.

Example Call

var utils = window["optimizely"].get("utils");

var cancelPolling = utils.poll(function() {
  timeRemaining = timeRemaining - 1000;

  // Update message based on how much time is remaining
  if (timeRemaining > 0) {
    var date = new Date(timeRemaining);
    headerElement.innerHTML = 'You have ' + date.getMinutes() + ':' + date.getSeconds() + ' before your reservation expires.';
  } else {
    headerElement.innerHTML = 'Your reservation has expired';
    cancelPolling();
  }
}, 1000);

Description

The poll function convenient wrapper around the setInterval function.

waitUntil()

Wait until the provided function returns true.

Syntax

utils.waitUntil(conditionFunction);

Parameters

Parameter and Type	Child Attribute	Description
conditionFunction function	N/A	A function that executes synchronously and returns a truthy value when the condition is met. Required.

Return value

Parameter and Type	Child Attribute	Description
Promise	N/A	An ES6-style Promise that will be resolved with the matching element.

Example Call

utils.waitUntil(function() {
  var productsShownOnThePage = document.querySelectorAll('.product-listing');
  return productsShownOnThePage && productsShownOnThePage.length > 200;
});

Description

This utility accepts a function that returns a Boolean value and returns a Promise that resolves when the supplied function returns true.

Examples

Warn after scrolling

Show the visitor an alert after the visitor has scrolled a significant distance down the page.

Example code for Warn after scrolling

// Retrieve the utils library
var utils = window["optimizely"].get('utils');

// We have infinite scroll enabled on the site. Wait until more than 200 products have been shown
// to prompt the user to try out our filter by color feature
utils.waitUntil(function() {
  var productsShownOnThePage = document.querySelectorAll('.product-listing');
  return productsShownOnThePage && productsShownOnThePage.length > 200;
}).then(function() {
  alert('Not finding what you\'re looking for? Try narrowing down your search using our new filter by color feature');
});