Tools

Das Tools-Objekt wird von ablyft.getTools() und ablyft.get('tools') zurückgegeben. Im JavaScript von Experiments und Variations steht es als ablyftTools zur Verfügung.

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

CookiesCopy Anchor Link

setCookieCopy Anchor Link

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

Setzt einen Cookie (SameSite=Lax, Path=/). days ist standardmäßig die maximale Cookie-Lebensdauer des Projects. Sofern ignoreDomain nicht true ist, wird der Cookie auf der Root-Domain (oder der benutzerdefinierten Cookie-Domain des Projects) gesetzt.

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) gibt den Wert oder null zurück.

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

removeCookieCopy Anchor Link

removeCookie(name) entfernt den Cookie auf dem aktuellen Host und auf der Root-Domain.

tools.removeCookie('my_cookie');

URLsCopy Anchor Link

parseUrlCopy Anchor Link

parseUrl(url?) zerlegt eine URL (Standard: aktuelle Seite) in protocol, host, hostname, port, pathname, search, hash, domain, tld und 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() gibt die Cookie-Domain zurück, z. B. .example.com (oder die benutzerdefinierte Cookie-Domain des Projects).

const rootDomain = tools.getRootDomain();

getUrlParameterCopy Anchor Link

getUrlParameter(name, url?) gibt den Parameterwert zurück, einen leeren String, wenn der Parameter keinen Wert hat, oder null, wenn er fehlt.

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

buildRedirectUrlCopy Anchor Link

buildRedirectUrl(url, keepQueryParameters?) gibt die endgültige Redirect-URL zurück (Standard keepQueryParameters = true). Bei true werden die aktuellen Query-Parameter und der Hash in das Ziel übernommen (Parameter des Ziels haben Vorrang). Liegt das Ziel auf einer anderen Domain, wird die aktuelle Variation-Zuweisung als URL-Parameter angehängt.

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

redirectCopy Anchor Link

redirect(url, keepQueryParameters?, preventLoops?)

Leitet den Visitor um (mit location.replace) und blendet die Seite währenddessen aus. Gibt false zurück, wenn der Redirect übersprungen wurde.

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() gibt die Variation-Zuweisung des Visitors im Format des Bucketing-URL-Parameters zurück (z. B. ["12345678_98765432"]), oder null, wenn es keine gibt. Nutze es, um die Zuweisung manuell an eine andere Domain zu übergeben.

const extension = tools.getSetBucketingUrlExtension();

Warten & BeobachtenCopy Anchor Link

pollCopy Anchor Link

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

Ruft pollingFn alle 10 ms auf, bis sie genau true zurückgibt, und ruft dann callbackFn auf. Gelingt das nicht innerhalb von timeoutMs (Standard 10000) oder timeoutAfterDomReadyMs (Standard 2000) nach DOM-Ready, wird callbackFnOnFail aufgerufen.

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

checkCopy Anchor Link

check(checkFn, callbackFn, callbackFnOnFail?) wertet checkFn einmal aus. Gibt sie genau true zurück, wird callbackFn aufgerufen, andernfalls callbackFnOnFail.

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

domLoadedCopy Anchor Link

domLoaded(callbackFn) ruft die Funktion auf, sobald das DOM interaktiv ist (sofort, wenn es das bereits ist).

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

domChangedCopy Anchor Link

domChanged(callbackFn) ruft die Funktion bei jeder DOM-Änderung auf (Children, Subtree, Attribute). Änderungen durch ABlyft selbst werden ignoriert.

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

waitForElementCopy Anchor Link

waitForElement(selector, fn, additionalData?)

Ruft fn(element, additionalData) für jedes Element auf, das selector entspricht, sobald es im DOM existiert (einmal pro Element). this ist ebenfalls das Element.

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

elementIsInViewCopy Anchor Link

elementIsInView(selector, fn, persistentObserving?)

Ruft fn(element) auf, wenn ein passendes Element in den Viewport scrollt. Bei persistentObserving = true bleiben Elemente weiter beobachtet. Später hinzugefügte Elemente werden miterfasst.

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

urlChangedCopy Anchor Link

urlChanged(mode, callbackFn)

Ruft die Funktion auf, wenn sich die URL ändert. mode ist 'polling' (vergleicht die URL alle 10 ms) oder 'history' (hängt sich in pushState, replaceState und popstate ein).

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)

Wartet (bis zu einer Stunde), bis ein Eintrag in window.dataLayer allen [key, value]-Paaren exakt entspricht, und ruft dann callbackFn auf.

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

watchDataLayerEntryCopy Anchor Link

watchDataLayerEntry(eventName, callback)

Ruft callback(entry) für den neuesten vorhandenen Data-Layer-Eintrag mit event === eventName und für jeden zukünftigen auf. Gibt eine Funktion zurück, die das Beobachten beendet. Die Erkennungsmethode (intercept oder polling) wird in den Snippet-Einstellungen des Projects festgelegt. Fehler innerhalb des Callbacks werden abgefangen und protokolliert.

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

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

Ressourcen ladenCopy Anchor Link

loadExternalCssCopy Anchor Link

loadExternalCss(url) hängt einen Stylesheet-Link an <head> an.

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

loadExternalJsCopy Anchor Link

loadExternalJs(url, callbackFn) hängt ein Script an <head> an und ruft callbackFn auf, wenn es geladen wurde.

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

ShopifyCopy Anchor Link

Zur Verwendung in Shopify-Theme- und Template-Variations, siehe Shopify Variations.

shopifyPreviewThemeCopy Anchor Link

shopifyPreviewTheme(themeId) wartet auf das Shopify-Objekt und leitet, falls das aktuelle Theme abweicht, auf die Preview des angegebenen Themes um.

tools.shopifyPreviewTheme(123456789);

shopifySwitchTemplateCopy Anchor Link

shopifySwitchTemplate(templateName) leitet auf ?view=<templateName> um, wenn die Seite noch keinen view-Parameter hat.

tools.shopifySwitchTemplate('landing-b');

Editor extensionsCopy Anchor Link

Wird von Variations verwendet, die mit dem Visual Editor und seinen Extensions erstellt wurden. Die Extension muss im Project existieren.

applyEditorExtensionCopy Anchor Link

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

Rendert eine Extension in die Variation und gibt die Instance-ID zurück (wird generiert, wenn sie fehlt). Unbekannte Extensions werden als Fehler protokolliert.

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

resetEditorExtensionCopy Anchor Link

resetEditorExtension(variationId, extensionId, instance) entfernt das CSS der Extension und führt ihren Reset-Code aus.

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

HilfsfunktionenCopy Anchor Link

hashCopy Anchor Link

hash(string) gibt einen kurzen hexadezimalen Hash eines Strings zurück.

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

generateRandomIdCopy Anchor Link

generateRandomId() gibt eine zufällige alphanumerische ID mit 10 Zeichen zurück.

const id = tools.generateRandomId();

pickPropertiesCopy Anchor Link

pickProperties(object, keys) gibt ein neues Objekt zurück, das nur die aufgelisteten Keys enthält (die auf dem Objekt existieren).

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

getNestedValueCopy Anchor Link

getNestedValue(object, path) liest einen verschachtelten Wert über einen Punkt-Pfad und gibt undefined zurück, wenn ein Teil fehlt.

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