JavaScript API#

The snippet gives every page one global object, window.tryfast. Use it to track conversions, pass consent, set visitor attributes, trigger experiments and debug. This page is the reference; to install the snippet see Install the snippet.

Calling TryFast before it has loaded#

Until the script has loaded, window.tryfast is an array that queues your calls. Push either an array of method name and arguments, or a function that receives the API:

window.tryfast = window.tryfast || [];
window.tryfast.push(["track", "purchase", { revenue: 79.90, currency: "EUR", orderId: "A-10442" }]);
window.tryfast.push(function (tf) {
  console.log("TryFast", tf.version, tf.getActive());
});

When the script has loaded it replaces the array with the API object and runs the queued calls in order. After that, push runs a call immediately, so tryfast.push([...]) works at any time and is the safest form in code that may run early. Methods never throw: invalid arguments are ignored and reported in the console when debugging is on.

Methods#

track(goalKey, options)#

Records a conversion for the goal with that key (the goal's key, for example purchase; see Goals).

tryfast.track("purchase", { revenue: 79.90, currency: "EUR", orderId: "A-10442", props: { plan: "pro" } });
tryfast.track("signup");

A track call with a key that matches no goal yet is kept, so you can create the goal after you see the event arrive.

set(key, value)#

Sets a visitor attribute, stored in the visitor's browser and usable in attribute targeting conditions. null deletes it. Attributes never leave the browser.

tryfast.set("plan", "pro");
tryfast.set("cart_value", 120);

identify(userId)#

Stores your user id as the attribute user_id. It does not change how visitors are split. Ignored in the exempt consent mode.

consent(granted)#

Tells TryFast your visitor's cookie banner decision (Privacy and consent). true stores the visitor id, sends buffered events and, with the default settings, applies experiments on the same page view. false clears TryFast's storage, drops buffered events and stops tracking. After true, later page views count as consented until false.

tryfast.push(["consent", true]);

optOut()#

Excludes this browser: sets the cookie tf_oo for 390 days, clears TryFast's other storage, and stops tracking and experiments on later page views. The URL parameter ?tf_optout=1 does the same.

event(name)#

Fires a custom event. Experiments with the trigger custom_event of that name activate, and custom_event audience conditions see it.

tryfast.event("opened_cart");

activate(experimentKey)#

Activates an experiment whose trigger is manual, by experiment key or id.

variation(experimentKey)#

Returns the key of the variation this visitor is assigned to ("control", "b", ...), or null.

getActive()#

Returns the experiments active on this page view: [{ experiment: { id, key }, variation: { id, key } }].

refresh()#

Re-evaluates targeting now. Route changes in single-page apps are detected automatically; call refresh() when your app renders new content without changing the URL.

onElement(selector, callback, options)#

Calls callback(element) for every element matching selector, now and as they appear later. Options: persist (keep watching, default true), timeout (ms). Returns a function that cancels.

when(condition, callback, options)#

Calls callback() once condition() returns true, checking every interval ms (default 50) until timeout ms (default 10,000). Returns a function that cancels.

state()#

Returns what the script decided on this page view, for debugging: version, project key, consent state, visitor id (null before consent), visit number, preview, and for each experiment whether pages, trigger and audience matched, the assigned variation and its source (sticky, hash, preview or shipped), why it was excluded, whether it applied and any errors. Also the goals fired, the event queue and timings.

Properties#

tryfast.version is the engine version; tryfast.ready is true after the first evaluation of the page.

Window events#

TryFast dispatches CustomEvents on window, so any tool on your page can react:

window.addEventListener("tryfast:exposure", function (e) {
  console.log(e.detail.experiment.key, "shows", e.detail.variation.key);
});

Abort reasons: disabled_param, unknown_project, killed, frozen, foreign_domain, bot, prerender_cancelled, opted_out, consent_denied, timeout, storage_unavailable, code_error, preview_invalid, redirect_off_domain.

When the project setting dataLayer events is on and your page already has a window.dataLayer array (TryFast never creates one), exposures and conversions are also pushed there (Integrations).

URL parameters#

All tf_* parameters are removed from the URL TryFast uses for targeting, goals and page views.

Preview, editor, debug and opt-out parameters work before consent: they write only to the tab's session storage (opt-out writes its one restricting cookie), and preview traffic is never counted.

Storage#

The script stores a random visitor id in the first-party cookie tf_vid (on your registrable domain, at most 390 days from its creation, never extended by visits) and its working state in localStorage and sessionStorage keys starting with tf_. With the default consent mode nothing is stored before consent. Privacy and consent lists every key with its purpose and lifetime.

Code in variations#

Variation JavaScript, experiment-wide JavaScript and the project's global script are written as the body of a function that TryFast calls with two arguments:

// runs as function (tf, ctx) { ...your code... }
var banner = document.createElement("div");
banner.textContent = "Free shipping on every order";
document.body.prepend(banner);
ctx.cleanup(function () { banner.remove(); });

• Variation and experiment-wide code: the return value is ignored. An exception stops that experiment for the page view (abort reason code_error) and leaves your page as it was.
• Targeting conditions of type js: return true, false, or a promise of either. Pending results count as false after the page's DOMContentLoaded plus 3 seconds.
• Triggers of type js: return true to activate now, or call ctx.activate() later on the page view.

Code is checked when you save it. A syntax error answers with the exact line and column, and nothing is published. TryFast never uses eval or new Function: your code is built into the project's script ahead of time, which keeps it compatible with a strict Content Security Policy.

Debugging#

Open any page with ?tf_debug=1. The console then shows the consent state, each experiment, each page rule and audience condition with the actual value, the trigger state, the assignment and its source, the changes applied (and selectors that matched nothing), goals fired and batches sent. tryfast.state() returns the same information as an object. ?tf_disable=1 shows the page without TryFast for comparison.

View as markdown