Tools

The tools object is returned by ablyft.getTools() and ablyft.get('tools'). Inside experiment and variation JavaScript it is available as ablyftTools.

const tools = ablyft.getTools();
// In experiment / variation JavaScript:
ablyftTools.waitForElement('.hero', (el) => { /* ... */ });

CookiesCopy Anchor Link

setCookieCopy Anchor Link

setCookie(name, value, days?, ignoreDomain?)

Sets a cookie (SameSite=Lax, Path=/). days defaults to the project's maximum cookie lifetime. Unless ignoreDomain is true, the cookie is set on the root domain (or the custom cookie domain of the project).

tools.setCookie('my_cookie', 'yes', 30); // 30 days, root domain
tools.setCookie('my_host_cookie', '1', 7, true); // current host only

getCookieCopy Anchor Link

getCookie(name) returns the value or null.

const value = tools.getCookie('my_cookie');

removeCookieCopy Anchor Link

removeCookie(name) removes the cookie on the current host and on the root domain.

tools.removeCookie('my_cookie');

URLsCopy Anchor Link

parseUrlCopy Anchor Link

parseUrl(url?) splits a URL (default: current page) into protocol, host, hostname, port, pathname, search, hash, domain, tld and subdomain.

const url = tools.parseUrl('https://shop.example.co.uk/cart?x=1');
// url.subdomain === 'shop', url.domain === 'example', url.tld === 'co.uk'

getRootDomainCopy Anchor Link

getRootDomain() returns the cookie domain, e.g. .example.com (or the custom cookie domain of the project).

const rootDomain = tools.getRootDomain();

getUrlParameterCopy Anchor Link

getUrlParameter(name, url?) returns the parameter value, an empty string if the parameter has no value, or null if it is missing.

const source = tools.getUrlParameter('utm_source');
const other = tools.getUrlParameter('id', 'https://example.com/?id=42');

buildRedirectUrlCopy Anchor Link

buildRedirectUrl(url, keepQueryParameters?) returns the final redirect URL (default keepQueryParameters = true). With true, the current query parameters and hash are merged into the target (parameters of the target win). When the target is on another domain, the current variation assignment is appended as URL parameter.

const target = tools.buildRedirectUrl('/landing-b/');

redirectCopy Anchor Link

redirect(url, keepQueryParameters?, preventLoops?)

Redirects the visitor (using location.replace) and hides the page meanwhile. Returns false if the redirect was skipped.

tools.redirect('/landing-b/');
tools.redirect('https://example.com/new/', false); // do not keep query parameters
tools.redirect('/landing-b/', true, false); // no loop protection

getSetBucketingUrlExtensionCopy Anchor Link

getSetBucketingUrlExtension() returns the visitor's variation assignment formatted for the bucketing URL parameter (e.g. ["12345678_98765432"]), or null if there is none. Use it to hand over the assignment to another domain manually.

const extension = tools.getSetBucketingUrlExtension();

Waiting & observingCopy Anchor Link

pollCopy Anchor Link

poll(pollingFn, callbackFn, callbackFnOnFail?, timeoutMs?, timeoutAfterDomReadyMs?)

Calls pollingFn every 10 ms until it returns exactly true, then calls callbackFn. If it does not succeed within timeoutMs (default 10000) or timeoutAfterDomReadyMs (default 2000) after the DOM is ready, callbackFnOnFail is called.

tools.poll(
  () => window.myLibrary !== undefined,
  () => console.log('library ready'),
  () => console.log('library not found'),
);

checkCopy Anchor Link

check(checkFn, callbackFn, callbackFnOnFail?) evaluates checkFn once. If it returns exactly true, callbackFn is called, otherwise callbackFnOnFail.

tools.check(
  () => document.body.classList.contains('checkout'),
  () => console.log('on checkout'),
);

domLoadedCopy Anchor Link

domLoaded(callbackFn) calls the function once the DOM is interactive (immediately if it already is).

tools.domLoaded(() => console.log('DOM ready'));

domChangedCopy Anchor Link

domChanged(callbackFn) calls the function on every DOM change (children, subtree, attributes). Changes made by ABlyft itself are ignored.

tools.domChanged(() => console.log('The page changed'));

waitForElementCopy Anchor Link

waitForElement(selector, fn, additionalData?)

Calls fn(element, additionalData) for every element matching selector as soon as it exists in the DOM (once per element). this is the element as well.

tools.waitForElement('.product-title', (el) => {
  el.textContent = 'New title';
});

elementIsInViewCopy Anchor Link

elementIsInView(selector, fn, persistentObserving?)

Calls fn(element) when a matching element scrolls into the viewport. With persistentObserving = true, elements stay observed. Elements added later are picked up.

tools.elementIsInView('.reviews', (el) => {
  console.log('reviews are visible', el);
});

urlChangedCopy Anchor Link

urlChanged(mode, callbackFn)

Calls the function when the URL changes. mode is 'polling' (compares the URL every 10 ms) or 'history' (hooks into pushState, replaceState and popstate).

tools.urlChanged('polling', () => console.log('URL is now', location.href));
tools.urlChanged('history', () => console.log('history navigation'));

Data layerCopy Anchor Link

checkForDataLayerEntryCopy Anchor Link

checkForDataLayerEntry(entrySpecs, callbackFn)

Waits (up to one hour) until an entry in window.dataLayer matches all [key, value] pairs exactly, then calls callbackFn.

tools.checkForDataLayerEntry(
  [['event', 'purchase'], ['currency', 'EUR']],
  () => console.log('purchase event found'),
);

watchDataLayerEntryCopy Anchor Link

watchDataLayerEntry(eventName, callback)

Calls callback(entry) for the latest existing data layer entry with event === eventName and for every future one. Returns a function that stops watching. The detection method (intercept or polling) is set in the project's snippet settings. Errors inside the callback are caught and logged.

const stop = tools.watchDataLayerEntry('add_to_cart', (entry) => {
  console.log('Item added', entry);
});

// later, if no longer needed
stop();

Loading resourcesCopy Anchor Link

loadExternalCssCopy Anchor Link

loadExternalCss(url) appends a stylesheet link to <head>.

tools.loadExternalCss('https://example.com/extra.css');

loadExternalJsCopy Anchor Link

loadExternalJs(url, callbackFn) appends a script to <head> and calls callbackFn when it has loaded.

tools.loadExternalJs('https://example.com/lib.js', () => console.log('loaded'));

ShopifyCopy Anchor Link

For use in Shopify theme and template variations, see Shopify variations.

shopifyPreviewThemeCopy Anchor Link

shopifyPreviewTheme(themeId) waits for the Shopify object and, if the current theme differs, redirects to the preview of the given theme.

tools.shopifyPreviewTheme(123456789);

shopifySwitchTemplateCopy Anchor Link

shopifySwitchTemplate(templateName) redirects to ?view=<templateName> if the page has no view parameter yet.

tools.shopifySwitchTemplate('landing-b');

Editor extensionsCopy Anchor Link

Used by variations created with the visual editor and its extensions. The extension must exist in the project.

applyEditorExtensionCopy Anchor Link

applyEditorExtension(variationId, selector, extensionId, extensionData, instance?)

Renders an extension into the variation and returns the instance ID (generated if omitted). Unknown extensions are logged as error.

const instance = tools.applyEditorExtension(12345678, 'body', '1', {
  headline: 'Inserted by an extension',
});

resetEditorExtensionCopy Anchor Link

resetEditorExtension(variationId, extensionId, instance) removes the extension's CSS and runs its reset code.

tools.resetEditorExtension(12345678, '1', instance);

UtilitiesCopy Anchor Link

hashCopy Anchor Link

hash(string) returns a short hexadecimal hash of a string.

const id = tools.hash('user@example.com');

generateRandomIdCopy Anchor Link

generateRandomId() returns a random 10-character alphanumeric ID.

const id = tools.generateRandomId();

pickPropertiesCopy Anchor Link

pickProperties(object, keys) returns a new object with only the listed keys (that exist on the object).

const small = tools.pickProperties({ a: 1, b: 2, c: 3 }, ['a', 'c']); // { a: 1, c: 3 }

getNestedValueCopy Anchor Link

getNestedValue(object, path) reads a nested value by dot path and returns undefined if any part is missing.

const coupon = tools.getNestedValue({ ecommerce: { coupon: 'SUMMER' } }, 'ecommerce.coupon');