ablyftTools / Helper Functions

Toolset/API for building Experiments on Single Page Applications (SPA)

On this page

General Usage

If you write the JavaScript code (experiment or variation), you have the possibility to use the ablyftTools. They make life easier for you as a developer of A/B tests in many places.
You can use the ablyftTools in the code editor or in your own scripts - e.g. if you work on a local copy of a page or create your A/B tests with Tampermonkey (for Google Chrome) / Greasemonkey (for Firefox).
You can always access the tools where the ABlyft snippet was loaded before.

Here's an example - even if it probably doesn't happen that way.

<html lang="en">
   <head>
      <script src="https://cdn.ablyft.com/s/12345678.js"></script>

      <!-- Your dev Script -->
      <script>
         var ablyftTools = window.ablyft.getTools();
         ablyftTools.domChanged(function(){
            console.log('Dom ready');
         });
      </script>

      ...

ABlyft Tools

ablyftTools.waitForElement

With ABlyft you have the possibility to wait for elements that are ready either directly after loading the page or at a much later time.
The DOM is permanently monitored via MutationObserver. If new elements of a CSS selector are stored in the DOM (e.g. loaded via AJAX or created via JavaScript), the callback function is executed directly.
The callback function call contains a NodeList like Array with the elements/nodes that were found.
It uses querySelectorAll for this purpose with the scope on the new elements.

Example

<!-- HTML Example -->
<ul id="myList">
    <li>Default Item 1</li>
    <li>Default Item 2</li>
    <li>Later inserted Item ()</li>
</li>

//Wait for the later inserted Item
var ablyftTools = window.ablyft.getTools();
ablyftTools.waitForElement('#myList > li', function(element){
    //In the example, we color the border red
    element.style.border = "1px solid red";
});

ablyftTools.elementIsInView

With this helper you can execute code whenever an DOM element is completely in the viewport.
The default is that the callback is triggered once.

Please note It is based on the IntersectionObserver. If you expect visitors using the Internet Explorer (before Edge), please provide a polyfill: https://github.com/w3c/IntersectionObserver/tree/master/polyfill#browser-support

//Wait for the DOM element to be completely visible in the viewport
var ablyftTools = window.ablyft.getTools();

//Trigger ONCE for the selected elements
ablyftTools.elementIsInView('#myList > li', function(element){
    console.log('Element viewed', element);
});

//Trigger EVERY TIME for the selected elements
ablyftTools.elementIsInView('#myList > li', function(element){
    console.log('Element viewed', element);
}, true);

ablyftTools.domChanged

With this helper you can execute code whenever the DOM has changed.
It is based on the MutationObserver.

//Wait for the DOM to be changed
var ablyftTools = window.ablyft.getTools();
ablyftTools.domChanged(function(){
    console.log('DOM was changed');
});

ablyftTools.checkForDataLayerEntry

Check window.dataLayer for matching entries - and if found, trigger a callback function.

/*
Check for a specific dataLayer entry by providing attributes that must match.
Here the following must be given:
	event = pageview
	page_location = the given url
*/
var ablyftTools = window.ablyft.getTools();
ablyftTools.checkForDataLayerEntry(
   [
      ['event', 'page_view'],
      ['page_location', 'https://www.example.com/test']
   ],
   function(){
      //activate(); //this would be used for the page trigger "callback"
   }
);

ablyftTools.watchDataLayerEntry

Watch window.dataLayer for entries of a specific event - and trigger a callback function with the matching entry.
Since entries are often pushed at a later time (e.g. after a user interaction or an AJAX request), the dataLayer is checked right away and continuously afterwards:

• If matching entries already exist, the callback is executed once immediately - with the latest existing entry.
• Every matching entry pushed afterwards executes the callback again.

The callback function receives the complete dataLayer entry (object) as its argument.
The function returns a stop function. Call it to stop watching.

You can call watchDataLayerEntry as often as you like. All calls share one single watcher, so there is no performance penalty for multiple calls.

/*
Watch for dataLayer entries of the event "virtPageView".
The callback is executed for an already existing entry (latest one)
and for every entry that is pushed later on.
*/
var ablyftTools = window.ablyft.getTools();
ablyftTools.watchDataLayerEntry('virtPageView', function(entry){
   console.log(entry);
   //activate(); //this would be used for the page trigger "callback"
});

//Access (nested) properties of the entry
ablyftTools.watchDataLayerEntry('purchase', function(entry){
   console.log(entry.ecommerce.transaction_id);
});

//Stop watching
var stop = ablyftTools.watchDataLayerEntry('virtPageView', function(entry){
   console.log(entry);
});
//...later on
stop();