Getting Started

To fully utilize the power of Taplytics.js, just follow the steps below:

1A Synchronous script loading

To best utilize Taplytics JS SDK you will want to install it as a synchronous loading script. This will ensure your users never see your content switching from baseline to their bucketed variations.

We recommend installing the Taplytics JS SDK script as high as possible in your <head> tag, ideally before any other analytics tools or other scripts are loaded.

To install the Taplytics JS SDK synchronously, use the following script tag. Replace {JS_SDK_TOKEN} in the src url with your own JS SDK Token from the Taplytics web dashboard:

<script type="text/javascript" src="https://js.taplytics.com/jssdk/{JS_SDK_TOKEN}.min.js"></script>

Example implementation:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <!-- Add other meta information -->
        <!-- Add stylesheets -->
        <script type="text/javascript" src="https://js.taplytics.com/jssdk/{JS_SDK_TOKEN}.min.js"></script>
        <!-- Add other scripts and content -->
    </head>
    <body>
    ...
    </body>
</html>

Pin SDK version

To pin the SDK to a specific version adjust the url in the src of the script tag to include the Taplytics JS SDK version after /jssdk/ in the url. For Example replace {VERSION_NUMBER} with the pinned SDK version:

<script type="text/javascript" src="https://js.taplytics.com/jssdk/{VERSION_NUMBER}/{JS_SDK_TOKEN}.min.js"></script>

Start Options

Start options allow you to control how certain SDK features, such as the default request timeout. For the synchronous script these need to be added as url encoded query parameters to the end of the src url on the script tag.

Start Option	Type	Description
test_experiments	Object	Set an Object containing pairs of experiment/variation combinations as key/value pairs to test with. Docs
cookie_domain	String	Set the domain that Taplytics will use to create cookies with. By default Taplytics will use a wildcard version of your top level domain that will work across sub-domains. For example a cookie from `web.taplytics.com` will be set as `.taplytics.com`, that will also work on another subdomain such as: `new.taplytics.com`.
user_attributes	Object	Set initial user attributes to be used during initial segmentation. This allows you to set custom data and user attributes that will be used by Taplytics to segment your user into experiments, user attributes set after calling `Taplytics.init()` won't be used for segmentation until the next session. Format of user attributes defined here.
track_adobe_analytics	Boolean	Enable Adobe Analytics events to be collected into Taplytics.
adobe_obj_name	String	The adobe_obj_name is optional. The default variable that comes with Adobe Analytics integration is `s`. The `s` variable contains all of the tracking tags to be sent to Adobe Analytics for a given visitor. You only need to provide this if you are using a custom variable name.

Any Object fields will need to be url encoded, to do that simply in Javascript:

const user_attributes = encodeURIComponent(JSON.stringify({
    "user_id": "user1", 
    "customValue": 10
}))

Example:

<script type="text/javascript" src="https://js.taplytics.com/jssdk/{JS_SDK_TOKEN}.min.js?cookie_domain=web.taplytics.com&test_experiments=%7B%22exp%22%3A%22var%22%7D&user_attributes=%7B%22user_id%22%3A%22user1%22%2C%22customValue%22%3A10%7D></script>

Session Length

A session is defined as user activity from the start of a new session until 30 minutes from last activity logged into Taplytics. If a user has not done anything to trigger updating their user information in Taplytics, we consider their next activity afterwards to be a new session.

You can also manually start a new session using the startNewSession method.

Taplytics.startNewSession();

1B Asynchronous script loading

Note: you only need to load the script once, do not load the synchronous script and the asynchronous script!

To install Taplytics JS SDK asynchronously, you have to include the following snippet into the header or body of your site:

<script type="text/javascript">
!function(){var t=window.Taplytics=window.Taplytics||[];if(window._tlq=window._tlq||[],!t.identify&&!t.loaded){t.loaded=!0,t.funcs=["init","identify","track","page","reset","propertiesLoaded","runningExperiments","variable","codeBlock"],t.mock=function(n){return function(){var e=Array.prototype.slice.call(arguments);return e.unshift(n),window._tlq.push(e),t}};for(var n=0;n<t.funcs.length;n++){var e=t.funcs[n];t[e]=t.mock(e)}t.load=function(){var t=document.createElement("script");t.type="text/javascript",t.async=!0,t.src="//cdn.taplytics.com/taplytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n)},t.load()}}();
</script>

This will load Taplytics.js asynchronously, so it will not affect your page load speed. We advise you use the synchronous script loading for any experiments applying content changes.

Other than that, all you have to do is initialize our SDK by using the init function:

Taplytics.init("JS_SDK_TOKEN");

Replace JS_SDK_TOKEN with your JS SDK token. You can find your token in the settings page of your project in the Taplytics dashboard.

❗️
When Taplytics.init() should be called
Taplytics.init() should be called if initializing asynchronously only. Calling Taplytics.init() alongside the synchronous script will cause multiple calls to Taplytics, which can result in undesired behaviour.

Note that this will send a page view event to us. If you want to disable the automatic page view event when Taplytics.js is initialized, check the documentation on the init function here and about calling the page function manually here.

Fast Mode

Deprecated: we advise using Synchronous script loading instead.

By default the JS SDK makes a request to Taplytics servers to generate its configuration, this gives us access to advanced segmentation options based on browser information and user data. However if the loading of your website is blocked by a Taplytics variable, you can enable Fast Mode which moves all the experiment distribution to the client-side SDK from Taplytics servers. Your project's configuration for Fast Mode is stored on a globally distributed CDN to reduce load times, however you will lose access to server-side segmentation based on user information.

Adding Fast Mode start option example:

Taplytics.init("API_KEY", {
    fast_mode: true
});

Pin SDK version

If you would like to pin the JS SDK to a specific SDK version change the //cdn.taplytics.com/taplytics.min.js url in the snip-it above using the following url where sdk_version is the version you would like to pin to: //cdn.taplytics.com/jssdk/sdk_version/taplytics.min.js

Start Options

Start options allow you to control how certain SDK features, such as the default request timeout.

Start Option	Type	Description
timeout	Number	Set the request timeout in seconds. If requests timeout variables will use the default value, but no events will be saved. The default timeout is 4 seconds.
test_experiments	Object	Set an Object containing pairs of experiment/variation combinations as key/value pairs to test with. Learn more.
fast_mode	Boolean	Enables client-side experiment distribution using CDN distributed configuration, but reduces segmentation options. Learn more.
cookie_domain	String	Set the domain that Taplytics will use to create cookies with. By default Taplytics will use a wildcard version of your top level domain that will work across sub-domains. For example a cookie from `web.taplytics.com` will be set as `.taplytics.com`, that will also work on another subdomain such as: `new.taplytics.com`.
user_attributes	Object	Set initial user attributes to be used during initial segmentation. This allows you to set custom data and user attributes that will be used by Taplytics to segment your user into experiments, user attributes set after calling `Taplytics.init()` won't be used for segmentation until the next session. For the format of user attributes, visit our reference documentation.
track_adobe_analytics	Boolean	Enable Adobe Analytics events to be collected into Taplytics.
adobe_obj_name	String	The adobe_obj_name is optional. The default variable that comes with Adobe Analytics integration is `s`. The `s` variable contains all of the tracking tags to be sent to Adobe Analytics for a given visitor. You only need to provide this if you are using a custom variable name.

Example:

Taplytics.init("API_KEY", {
    timeout: 10,
    fast_mode: true,
    test_experiments: {
        "JS experiment": "Variation 1",
        "JS experiment 2": "baseline"
    }
});

2. Identify Users

Using the identify function, you can let us know who the current user is on the page. It can also be used to let us know about any user attribute that can be used for segmentation in our system.

We accept a few known attributes and all unknown attributes are saved as custom attributes that can also be used. Read more about the identify function here.

Here's a quick example:

Taplytics.identify({
    email: "[email protected]",
    user_id: "abbc-123-axx-123-okl-123",
    first_name: "Nima",
    last_name: "Gardideh",
    age: 23,
    gender: "male",
    friends_count: 10,
    purchases_count: 10,
    store_credit: 102.14
});

3. Track Events

You can use the track function to send us events and let us know what actions the user is performing on the page. You can use these events within Taplytics to create more personalized and rich a/b tests and push notifications.

Here's how to do it:

Taplytics.track("Purchase", 10, {
    product_id: 100,
    product_name: "Cyan-Pink Shirt",
    product_price: 80.00
});

Note that you can send us revenue information by passing a value to the function and any other data that you can use when creating segments within Taplytics. Read more about the track function here.

4. Track Page Views

As we mentioned earlier, we automatically track page views for you when you initialize our SDK. You will have to call the page function if you would like to perform the following; rename your page views, attach more information to your page views, or if you're using a one-page web framework (Angular, React, Backbone, Ember, etc.).

You can specify a category, a name, and extra attributes when calling the page function:

Taplytics.page("Product Listings", "Shirts", {
    products_count: 100
});

Note that you can call the function by itself without any arguments as well. Read more about the page function here.

5. Experiments

To setup code experiments with the Taplytics JS SDK check out this section here.

6. Opt-In/Out

Using the User Opt-In / Opt-Out APIs allows you to simplify the process to get user consent for analytics tracking and experimentation. Calling optOutTracking will disable all Taplytics analytics tracking and experiments and delete all Taplytics cookies, and calling optInTracking will re-enable all Taplytics analytics tracking and experiments. You can retrieve the current status using: hasUserOptedOutTracking.

function optIn() {
    console.log("opt in")
    Taplytics.optInTracking();
}

function optOut() {
    console.log("opt out")
    Taplytics.optOutTracking();
}

function hasOptedOut() {
    let hasUserOptedOut = Taplytics.hasUserOptedOutTracking();
    console.log(`Has user opted out tracking: ${hasUserOptedOut}`)
}

7. Adobe Analytics integration

Adobe Analytics by default uses s.t() and s.tl() for tracking page views and link clicks. By setting track_adobe_analytics variable to true in Taplytics.init function, We inject our tracking code into the definitions of these functions. So whenever s.t() or s.tl() is called on the page, It first sends those events to Taplytics before sending them to Adobe Analytics.
By default, Taplytics assumes adobe analytics tracking variable to be s. If you use a custom variable, then make sure to provide that during taplytics initialization with adobe_obj_name variable.

8. CNAME Aliasing

To prevent adblocks from blocking requests to our api servers, you can setup a CNAME on your domain that points to our API domains:

https://api.taplytics.com
https://ping.taplytics.com

Once you have your CNAME setup, you can pass in as options to the sync script URL or as options in Taplytics.init.

Taplytics.init("TOKEN", {
    alias_host: {
        api_host: 'https://api-alias.your-domain.com',
        ping_host: 'https://ping-alias.your-domain.com'
    }
});

<script type="text/javascript">
  var head = document.getElementsByTagName('head')[0];
  var script = document.createElement('script');
  script.type = 'text/javascript';
  const alias = {
    api_host: 'https://api-alias.your-domain.com',
    ping_host: 'https://ping-alias.your-domain.com'
  }
  const encodedAlias = encodeURIComponent(JSON.stringify(alias));
  script.src = `https://js.taplytics.com/jssdk/{YOUR_TOKEN}.min.js?alias_host=${encodedAlias}`;
  head.appendChild(script);
</script>

Experiments

Creating experiments is easy, using the Taplytics Javascript SDK you can create code-based experiments with Dynamic Variables or Code Blocks. You can find documentation on how to do this below.

Dynamic Variables & Code Blocks

To see and modify these variables or blocks on the dashboard, the SDK must be launched and this code containing the variable or block must be navigated to a least once.

Dynamic Variables

Taplytics variables are values in your website that are controlled by experiments. Changing the values can update the content or functionality of your website. Variables are reusable between experiments.

Asynchronous

Asynchronous variables take care of insuring that the experiments have been loaded before returning a value. This removes any danger of tainting the results of your experiment with bad data. What comes with the insurance of using the correct value is the possibility that the value will not be set immediately. If the variable is constructed before the experiments are loaded, you won't have the correct value until the experiments have finished loading. If the experiments fail to load, then you will be given the default value, as specified in the variables constructor.

Asynchronous variables take three parameters in its constructor:

Variable Name (String)
Default Value (String, Number, or Boolean)
Updated Function (Function)

The type of the variable is defined by the type of the default value, and can be a String, Number or a Boolean.

For example, using a variable of type Number:

Taplytics.variable("JS Number", 1, (value) => {
    // function called when experiment config has loaded and value has been set
    console.log("JS Number value: " + value);
});

When the SDK has loaded the experiment config from our servers, the updated block will be called with that updated value.

Synchronous

Due to the synchronous nature of the variable, if it is used before the experiments have been loaded from Taplytics servers, it's value will be the default value rather than the value set for that experiment. This could taint the results of the experiment. In order to prevent this you can ensure that the experiments are loaded before using the variable. This can be done using the propertiesLoaded method, as an example:

Taplytics.propertiesLoaded(() => {
    var syncVar = Taplytics.variable("JS String", "default");
    console.log("JS String Sync value: " + syncVar.value);
});

Synchronous variables take two parameters in its constructor:

Variable Name (String)
Default Value (String, Number, or Boolean)

The type of the variable is defined by the type of the default value, and can be a String, Number or a Boolean.

Code Blocks

Similar to Dynamic Variables, Taplytics has an option for 'Code Blocks'. Code blocks are linked to Experiments through the Taplytics website very much the same way that Dynamic Variables are, and will be executed based on the configuration of the experiment through the Taplytics website. A Code Block is a function that can be enabled or disabled depending on the variation. If enabled, the function will be executed asynchronously once the experiment config has loaded from our servers. If disabled, the function will not be executed.

A Code Block can be used alongside as many other Code Blocks as you would like to determine a combination that yields the best results. Perhaps there are three different Code Blocks on one view. This means there could be 8 different combinations of Code Blocks being enabled / disabled on that view if you'd like.

Example:

Taplytics.codeBlock("enableFeature", function() {
    // enable your feature here
});

Get Running Experiments

If you would like to see which variations and experiments are running, use the runningExperiments function which will return the current experiments and their running variation once the SDK has loaded the config from our servers. An example:

Taplytics.runningExperiments(function(expAndVars) {
    // For example: 
    // expAndVars = {
    //  "Experiment 1": "baseline",
    //  "Experiment 2": "Variation 1"
    //};
});

NOTE: The block can return asynchronously once Taplytics config has loaded. The block will return an Object with experiment names as the key values, and variation names as the values.

Testing Experiments

To test/QA specific experiment and variation combinations use the test_experiments option with an Object containing keys of the experiment names, and values of variation names (or baseline).

Taplytics.init("API_KEY", {
    test_experiments: {
        "JS experiment": "Variation 1",
        "JS experiment 2": "baseline"
    }
});

Feature Flags

Taplytics feature flags operate in synchronous mode. Synchronous feature flags are guaranteed to have the same value for the entire session and will have that value immediately after construction.

if (Taplytics.featureFlagEnabled("featureFlagKey")) {
    //Put feature code here, or launch feature from here
}

Due to the synchronous nature of feature flags, if it is used before the feature flags have been loaded from Taplytics servers, it will default to as if the feature flag is not present. In order to prevent this you can ensure that the feature flags are loaded before using the feature flag. This can be done using the propertiesLoaded method, as an example:

Taplytics.propertiesLoaded((loaded) => {
    if (Taplytics.featureFlagEnabled("featureFlagKey")) {
        // Put feature code here, or launch feature from here
    }
})

Running Feature Flags

If you would like to see which feature flags are running, there exists a getRunningFeatureFlags function which provides a callback with an object that contains the currently active feature flags. An example:

Taplytics.runningFeatureFlags((runningFF) => {
    // For example runningFF will contain:
    //    {
    //        "featureFlagKey": "My First Feature Flag",
    //        "key with spaces": "My Second Feature Flag"
    //    }
});

NOTE: The block can return asynchronously once Taplytics properties have loaded. The feature flags will be provided in an object where the properties are the
feature flag key names and their corresponding values are the names of the associated feature flags.

Reference

Below you will find the APIs that Taplytics.js exposes.

If you haven't already, check out our guide on how to get started with our Javascript SDK here.

init

Usage: Taplytics.init(token, [options])

Instantiates Taplytics.js.

This should be the first function to be called on the page before all other functions. You can find your JS SDK Key in the Settings section of your project.

It also automatically calls the page function (with no arguments) right away. You can disable this in the options.

Arguments

token (string): Taplytics JS SDK
[options] (Object): The options object.

Options Params	Type	Description
timeout	Number	Set the request timeout in seconds. If requests timeout variables will use the default value, but no events will be saved. The default timeout is 4 seconds.
test_experiments	Object	Set an Object containing pairs of experiment/variation combinations as key/value pairs to test with. Learn more.
fast_mode	Boolean	Enables client-side experiment distribution using CDN distributed configuration, but reduces segmentation options. Docs
cookie_domain	String	Set the domain that Taplytics will use to create cookies with. By default Taplytics will use a wildcard version of your top level domain that will work across sub-domains. For example a cookie from `web.taplytics.com` will be set as `.taplytics.com`, that will also work on another subdomain such as: `new.taplytics.com`.
user_attributes	Object	Set inital user attributes to be used during inital segmenation. This allows you to set custom data and user attributes that will be used by Taplytics to segment your user into experiments, user attributes set after calling `Taplytics.init()` won't be used for segmentation until the next session.

Returns

(Object): Returns the Taplytics object on success, useful for chaining. When no token is provided, it returns undefined.

Example

// Without options
Taplytics.init("js-sdk-token");

// With some options
Taplytics.init("js-sdk-token", {
    auto_page_view: false,
    log_level: 1
});

identify

Usage: Taplytics.identify(user_attributes)

Identifies the user that's currently on the page. This helps link their activity on the web with their activity on other platforms (iOS, Android).

You should call this function as soon as a user signs up or has logged in. You should also call it at least once per page.

Arguments

[user_attributes={}] (Object): User Attributes object.
[user_attributes.user_id] (string/integer): User's ID (optional).
[user_attributes.email] (string): User's Email (optional).
[user_attributes.gender] (string): User's Gender, one of male or female (optional).
[user_attributes.age] (integer): User's age as a number (optional).
[user_attributes.firstName] (integer): User's first name (optional).
[user_attributes.lastName] (integer): User's last name (optional).
[user_attributes.name] (integer): User's full name (optional).
[user_attributes.avatarUrl] (string): User's avatar/profile image URL (optional).
[user_attributes.custom_attr_name] (string/integer/object): Any extra custom attributes (optional).

Returns

(Object): Returns the Taplytics object, useful for chaining.

Example

// With just a few named user attributes
Taplytics.identify({
    email: "[email protected]",
    age: 23,
    gender: "male",
    firstName: "Nima",
    lastName: "Gardideh"
});

// With non-named custom attributes
Taplytics.identify({
    user_id: 1015,
    loyalty_group: "very_loyal",
    purchases_count: 15,
    friends_Count: 800
});

track

Usage: Taplytics.track(event_name, [value], [event_attributes])

Tracks the occurrence of an event for the current visitor (anonymous or identified).

Note that value is identified as revenue. If you want to send information about the event itself, send it through event_attributes.

Aliases

This function can also be called as follows:
Taplytics.track(event_name, [event_attributes])

Arguments

event_name (string): Event name.
value (integer/double): Value of the event (optional).
event_attributes (Object): Event attributes to be sent with the event (optional).

Returns

(Object): Returns the Taplytics object, useful for chaining.

Example

// Simple event
Taplytics.track("Clicked Button");

// Event with value (revenue)
Taplytics.track("Purchased", 180.50);

// Event with value (revenue) and extra attributes
Taplytics.track("Purchased", 180.50, {
    product_id: 100,
    product_name: "Shirt"
});

// Event just with attributes
Taplytics.track("Finished Tutorial", {
    time_on_tutorial: 100
});

page

Usage: Taplytics.page([category], [name], [page_attributes])

Tracks a page view. This is called once automatically from the init function.

You can call it manually yourself to structure the page view events, as well as when you have a single page Javascript application that does its own routing.

Currently, we do not listen on window.History state change events to do this automatically.

Aliases

This function can also be caleld as follows:
Taplytics.page([name], [page_attributes]);

Arguments

[category] (string): Page Category (optional).
[name] (string): Page Name (optional).
[page_attributes] (Object): Page attributes object.

Returns

(Object): Returns the Taplytics object, useful for chaining.

Example

// Track a page view with no attributes
Taplytics.page();

// Track it by setting a name
Taplytics.page("Page Name");

// Track a page view with a category and a name
Taplytics.page("Product Listings", "Shirts");

// Track a page view with a name and attributes
Taplytics.page("Shirts Page", {
    products_count: 150
});

// Track a page view with a name, a category, and attributes
Taplytics.page("Product Listings", "Shirts", {
    products_count: 150
});

reset

Usage: Taplytics.reset()

Resets the user object and assumes the visitor is now anonymous. This can be used to deatach the visitor from the user that you had used identify on earlier in the session.

Returns

(Object): Returns the Taplytics object, useful for chaining.

Example

// Reset user
Taplytics.reset();

propertiesLoaded

Usage: Taplytics.propertiesLoaded([callback])

Calls the function provided when the SDK's properties have loaded from Taplytics's servers.

Arguments

[callback] (function): function to callback when properties have loaded.

Example

Taplytics.propertiesLoaded(function() { 
    // properties have loaded
});

runningExperiments

Usage: Taplytics.runningExperiments(callback)

Calls the function provided with an Object containing the running experiments and variation names when the SDK's config has loaded from Taplytics's servers.

Arguments

callback (function): function to callback with running experiments and variations. With the Object's keys as experiment names, and values as the variation name.

Example

Taplytics.runningExperiments(function(expAndVars) {
    // For example: 
    // expAndVars = {
    //  "Experiment 1": "baseline",
    //  "Experiment 2": "Variation 1"
    //};
});

variable

Usage: Taplytics.variable(name, defaultValue, [updatedBlock])

Creates a Taplytics Variable with values that are controlled by your running experiments.

Arguments

name (string): Variable Name.
defaultValue (string/number/boolean): Variable's default value.
[updatedBlock] (function): Update block to be called when the Variable's value is set (optional).

Returns

(TLVariable): Returns a Taplytics Variable, use value to get the variable's value

Example

// Using a asynchronous variable with the updated block
Taplytics.variable("JS String", "default", function(value) {
    console.log("JS String value: " + value);
});

// Using a synchronous variable
Taplytics.propertiesLoaded(function() {
    var syncVar = Taplytics.variable("JS String", "default");
    console.log("JS String Sync value: " + syncVar.value);
});

codeBlock

Usage: Taplytics.codeBlock(name, codeBlock)

Creates a Taplytics Code Block that will be run if enabled for the running experiment/variation through Taplytics website.

Arguments

name (string): Variable Name.
codeBlock (function): Code Block to be called if enabled for the experiment's variation.

Example

Taplytics.codeBlock("JS CodeBlock", function() {
    console.log("JS Code Block");
    // run your code here
});

Enable the Visual Editor

Making visual edits on the web with Taplytics is super easy! Similar to mobile, once the visual web editor tool has been enabled it's as simple as hovering over the element you'd like to edit and making the change.

All you need to do to enable the visual web editing tool is provide a google email address and then download the Taplytics Chrome Web Extension. From there you'll be able to make edits directly from on your website.

Making Visual Edits

All edits are done on your actual website and are only launched to production once you've started the experiment.

Using the visual editor you are able to make most types of changes to any static element on your website, including copy, size, colour, font, and image changes.

Changes are applied to the CSS selectors on each page and will be applied to specific pages based on the URL path.

If you'd like changes to stick to additional pages there is an option to "Match on all URL's". Checking this box will ensure changes made on one page will carry over to the matching element on another page. Taplytics does this by matching both on the base URL and then looking for additional CSS selectors to carry the change over to additional pages.

Check out our Web Visual Experiments User Guide

Getting Started

1A Synchronous script loading

Pin SDK version

Start Options

Session Length

1B Asynchronous script loading

❗️When Taplytics.init() should be called

Fast Mode

Pin SDK version

Start Options

2. Identify Users

3. Track Events

4. Track Page Views

5. Experiments

6. Opt-In/Out

7. Adobe Analytics integration

8. CNAME Aliasing

Experiments

Dynamic Variables & Code Blocks

Dynamic Variables

Asynchronous

Synchronous

Code Blocks

Get Running Experiments

Testing Experiments

Feature Flags

Running Feature Flags

Reference

init

identify

track

page

reset

propertiesLoaded

runningExperiments

variable

codeBlock

Enable the Visual Editor

Making Visual Edits

❗️
When Taplytics.init() should be called