JS SDK

📘
JavaScript SDK Update
Welcome to version 3.0.0 of the Taplytics JS SDK!
We’ve made lots of improvements to our JS SDK to now include more promises and callbacks to methods, as well as unifying method signatures with our Mobile SDKs to ensure consistency across all platforms.
To learn how to transition from a previous version to the latest version, please visit our JS SDK update guide here.
Not ready for an upgrade? View the previous version of the JS SDK docs here.

Getting Started

To fully utilize the power of Taplytics.js, start by initializing Taplytics using one of the methods below.

1. Installation

i) NPM Module

The recommended way to include the JS SDK is to bundle it with the rest of your application code using our NPM module.

Add the SDK as a dependency to your project

npm install @taplytics/js-sdk --save

yarn add @taplytics/js-sdk

Import the SDK somewhere in your application, and initialize using your project token:

import Taplytics from '@taplytics/js-sdk';

Taplytics.start('JS_SDK_KEY');

ii) Using the CDN

If you want to load the SDK on your webpage separately from your main application bundle,
you can do so using a script tag. Place the following as high as possible in your <head> tag:

<script type="text/javascript" src="https://cdn.taplytics.com/jssdk/latest/taplytics.min.js" referrerpolicy="no-referrer-when-downgrade"></script>
<script type="text/javascript">
	Taplytics.start('JS_SDK_KEY');	
</script>

Including referrerpolicy is highly recommended for Visual Web Editor users but can be omitted if necessary.

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://cdn.taplytics.com/jssdk/latest/taplytics.min.js" referrerpolicy="no-referrer-when-downgrade"></script>
        <script type="text/javascript">
            Taplytics.start('JS_SDK_KEY');
        </script>
        <!-- Add other scripts and content -->
    </head>
    <body>
    ...
    </body>
</html>

Pin SDK version

To pin the SDK to a specific version, adjust the CDN URL path to include the version number

<script type="text/javascript" src="https://cdn.taplytics.com/jssdk/3.0.0/taplytics.min.js"></script>

Start Options

Start Options allow you to control how certain SDK features function, such as the default request timeout.
Simply add them to the Taplytics.start call as a second argument.

Start Option	Type	Description
alias_host	Object	This is used to replace the hosts of the urls to bypass adblockers
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`.
manual_trigger_edits	Boolean	Turn this ON to prevent applying visual edits automatically by the sdk
test_experiments	Object	Set an Object containing pairs of experiment/variation combinations as key/value pairs to test with. More information can be found here.
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.
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. Format of user attributes defined here.
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.
track_adobe_analytics	Boolean	Enable Adobe Analytics events to be collected into Taplytics.
user_bucketing	Boolean	Enables User-Based bucketing in the SDK and requires a `user_id` to provide consistent bucketing rather than bucketing by a device ID. Default is false. For more information please view this doc first.

Example:

Taplytics.start("JS_SDK_KEY", {
	timeout: 10,
	test_experiments: {
	    "JS experiment": "Variation 1",
	    "JS experiment 2": "baseline"
	},
	user_attributes:{
	    email: "[email protected]",
	    qa_user: true,
	    purchases: 15
	}
})

Caching & SDK Timeouts

Built into each Taplytics client-side SDK is a caching system that saves experiment and feature flag values locally on each session. These values are saved locally for several reasons, but the two primary ones are:

To keep the user experience consistent when Taplytics’ servers are unreachable for any reason
To minimize outbound requests to Taplytics, allowing configuration data to be used throughout a session if successfully loaded and saved

The Taplytics SDK also enables you to configure the request timeout, which specifies the time within which the Taplytics SDK must return a response. By default, the timeout value is set to 4000ms on all client-side SDKs. If the default timeout value is not appropriate for your application, you can adjust the timeout for your specific requirements within the starting parameters.

If a response isn’t returned within the time specified, the request ends. The Taplytics SDK will either return the last cached value saved within your device, or if there was no previously cached value, the SDK will use variable default values.

Whichever is used, cached values or defaults, the SDK will use those values for the remainder of the session. Updated values from our SDK will still attempt to download on timeouts in the background and will be cached and ready to use on the next session if any retry is successful.

2. Usage

A basic usage example of the SDK is shown below. More detailed examples can be found in the following sections

import Taplytics from '@taplytics/js-sdk';

async function main() {
    // initialize Taplytics with your project token and wait for it to finish
    // pass identifying user attributes
    await Taplytics.start('JS_SDK_KEY', {
        user_attributes: {
            user_id: 'my-user',
            customData: {
                'membership': 'paid'
            }
        }
    })
    
    const themeVar = Taplytics.variable('theme', 'light');
    console.log(themeVar.value);

    // add additional data to the current user. This persists the data to Taplytics' servers but does not obtain
    // new experiments
    await Taplytics.setUserAttributes({
        customData: {
            'my-property': 'my-value'
        }
    })
    
    // log a custom event for later analysis
    Taplytics.logEvent('my-event')
    
    // change user identity by providing a new user_id
    // this starts a new session and retrieves the new set of experiments
    await Taplytics.setUserAttributes({
        user_id: 'different-user',
        customData: {
            'membership': 'free'
        }
    })
    
    // reset the current user and retrieve a new set of experiments for a new anonymous user
    await Taplytics.resetUser()
}

main()

Most methods on the Taplytics JS SDK are asynchronous. They return promises which resolve when the operation is complete.

3. Identify Users

Using the setUserAttributes function, you can let us know who the current user is on the page.
The method 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, as well as a customData property that can be used to set any kind of data.
The user_id property is used to represent the user's unique identity.
Read more about the setUserAttributes function here.

Here's a quick example:

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

User Attributes set before the start function is called, will be used for experiment segmentation on the first session of your app.
Any attributes that are set after the start function is called, will not be used for experiment segmentation until the next session of your app.

To manually start a new session, check out our docs here.

The method returns a promise which can be awaited to ensure that the operation has completed before continuing.

await Tapyltics.setUserAttributes({
    user_id: "abbc-123-axx-123-okl-123"
})

4. Track Events

You can use the logEvent 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.

Here's how to do it:

Taplytics.logEvent("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 logEvent function here.

5. Experiments and Feature Flags

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

To setup feature flags with the Taplytics JS SDK check out the Feature Flags 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 Taplytics.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. Integrations

Visit our 3rd Party Integrations page to learn more about our integrations with your favourite analytics platforms!

Adobe

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.start function, We inject our tracking code into the definitions of these functions. Learn more about the Adobe integration for Web here.

Amplitude

Taplytics will automatically track incoming Amplitude events and you have the option to send experiment/variation data back to Amplitude. Learn more about the Amplitude integration for Web here.

Google Analytics

Taplytics will automatically track incoming Google Analytics events and you have the option to send experiment/variation data back to Google Analytics. Learn more about the Google Analytics integration for Web here.

Mixpanel

Taplytics can send experiment/variation data back to Mixpanel. Learn more about the Mixpanel integration for Web here.

MParticle / Segment

Integrate Taplytics with mParticle or Segment to connect your users and events to Taplytics without needing to create them separately. To get started, visit their respective pages here:

Extra Start Options

MParticle and Segment both allow you to enable/disable Taplytics specific Start Options from their platforms but you may also add start options using the following code to append and/or override existing start options. This is helpful when the options don't exist on mParticle/Segment.

<script>
   window.tl_options = {
      'cookie_domain': '...',
      'manual_trigger_edits': true,
      'user_attributes':{ ... },
      ...
   }
</script>

</script> 
   // Initialize Segment/mParticle 
</script>

8. Adblockers: How to Navigate

Custom Domain Proxy

Implement a Custom Domain Proxy to bypass 3rd party cookie blockers that block requests to Taplytics SDKs and APIs.
The Custom Domain Proxy allows all Taplytics requests to be sent through your recognized domain.
A CNAME hostname and certificate will need to be created in order to leverage this feature and both options can be customized if needed.

Identifying a Hostname and Certificate Owner
The first step involves identifying a hostname to use as the CNAME to Taplytics’ service as well as deciding whether you'd like Taplytics to manage a new certificate or manage the certificate yourselves.

If there is more than one service in use, each one will need a unique CNAME
If you'd like to create a custom hostname, you'll need to provide us with the hostname. Otherwise, Taplytics will create one for you
If you need to manage the certificate instead of having Taplytics manage the renewal, you'll need to provide both the Certificate and Private Key for the certificate(s) that you've created

Setup Hostname and Certificate
Taplytics to start the setup with the certificate and hostname. We can start this process immediately if you do not need to customize your hostname or certificate.
DNS Validation
Once the setup is complete, two DNS record will be provided by Taplytics and you will need to add those records to your DNS provider (TXT validation records).
Additional Setup Step
Once validation is complete, there may be an extra step involved here with Taplytics depending on your SDK configuration. Taplytics will let you know if this is needed.
Creating a CNAME
Once all steps are complete, Taplytics will send the details for the DNS CNAME. Once added, the service will be immediately available at the given hostname. You can use this hostname for all requests to Taplytics instead.
Self-Managed Certificates
If you are managing your own certificate, please provide Taplytics with any new certificates if they expire in the future. Failure to do so will result in an invalid certificate error.

If you have any questions regarding this process, please reach out to your CSM or to our support team.

CNAME Aliasing

Implementing CNAME aliasing can prevent adblockers from blocking requests to our api servers and our SDK. In order to workaround adblockers, please follow the implementation details below to add the alias_host start option and update the url to the SDK. In addition, Taplytics also requires a certificate for the domain that you will create a CNAME record for. If you would prefer not to create a certificate and send it to Taplytics, see the “Using a Reverse Proxy” section below.

1. Setup a CNAME on a DNS which points to our API Domains:

https://api-alias.your-domain.com -> https://api.taplytics.com
https://ping-alias.your-domain.com -> https://ping.taplytics.com

Once you have generated a CNAME, proceed in modifying your existing JS SDK loading scripts and include the alias_host start option.

Two options exist in loading the JS SDK. Please follow one of the two options below to successfully load the JS SDK dependent on your configuration.

a) NPM package Loading

Add the alias_host start option as a URL parameter to the start method

import Taplytics from '@taplytics/js-sdk'

Taplytics.start({
  api_host: 'https://api-alias.your-domain.com',
  ping_host: 'https://ping-alias.your-domain.com'
})

b) Script Tag Loading

Replace the script src attribute cdn.taplytics.com/jssdk/latest/taplytics.min.js with api-alias.your-domain.com/jssdk/latest/taplytics.min.js

<script src="https://api-alias.your-domain.com/jssdk/latest/taplytics.min.js"></script>

Add the alias_host start option and your CNAME domains

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

2. Generate a new Certificate

You will then need to create a new Certificate for the domain you wish to whitelist. The certificate will contain 4 files, three of which are required:

cert.pem*
privkey.pem*
chain.pem*
fullchain.pem

Required: cert.pem, privkey.pem, and chain.pem.

To submit your certificate in addition to completing the setup, please contact your CSM or email us directly at [email protected].

Using a Reverse Proxy

Another way to navigate adblockers is to implement a reverse proxy from your server to ours. In this case, rather than using a CNAME to direct traffic from specific subdomains to our API and PING domains, you will need to implement routes on your server that would proxy traffic from your server to ours. Please note: unlike the CNAME option above, this option does not require a certificate to be created.

Below is a sample NginX configuration exemplifying reverse proxies:

...
location /tap-api/ {
 proxy_pass https://api.taplytics.com/;
}
location /tap-ping/ {
 proxy_pass https://ping.taplytics.com/;
}
...

Once you have implemented routes on your servers, proceed in modifying your existing JS SDK loading scripts and include the alias_host start option.

Two options exist in loading the JS SDK. Please follow one of the two options below to successfully load the JS SDK dependent on your configuration.

a) NPM package Loading

Add the alias_host start option as a URL parameter to the start method

import Taplytics from '@taplytics/js-sdk'

Taplytics.start({
    api_host: 'https://your-domain.com/tap-api',
    ping_host: 'https://your-domain.com/tap-ping'
})

b) Script Tag Loading

Replace the script src attribute cdn.taplytics.com/jssdk/latest/taplytics.min.js with your-domain.com/tap-api/jssdk

<script src="https://api-alias.your-domain.com/jssdk/latest/taplytics.min.js"></script>

Add the alias_host start option and your CNAME domains

Taplytics.start("JS_SDK_Key", {
    alias_host: {
        api_host: 'https://your-domain.com/tap-api',
        ping_host: 'https://your-domain.com/tap-ping'
    }
});

After completing the steps above, users should be able to freely maneuver around adblockers and prevent them from blocking requests to our api servers and our SDK.

Sessions

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, their next interaction with Taplytics will be in a new session.

Start New Session

You can also manually start a new session using the startNewSession method if you need to load a new configuration from Taplytics. ie. After setting custom user attributes for segmentation.

Note that changing the user_id will also start a new session and fetch a new configuration from Taplytics automatically, making this call unnecessary in those cases.

Taplytics.startNewSession()

This method also returns a promise, and can be awaited if you need to wait for the new configuration to be loaded before continuing.

Experiments

Creating experiments is easy, using the Taplytics Javascript SDK you can create code-based experiments with Dynamic Variables. Continue reading to find out how to set up those up in code below and find instructions on setting up experiments on the Taplytics dashboard here.

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 but may cause issues if they are used in multiple active experiments.

A Taplytics variable instance is obtained by calling the Taplytics.variable method. The type of the variable is defined by the type of the default value, and can be a String, Number, Boolean or plain Object.

For example, using a variable of type String:

const variable = Taplytics.variable("JS String", "default")
console.log("variable value: ", variable.value)

If the variable is instantiated before Taplytics has loaded the experiment configuration from the server, the value property will be set to the default value. Once the configuration has been loaded, the value will be changed to reflect the value in that configuration.

In order to ensure that the variable value is correct and isn't using the default, it is good practice to wait for
Taplytics to initialize before accessing variables. This can be done by awaiting the Taplytics.start method, or by calling the Taplytics.waitForLoaded method if Taplytics has already been started somewhere else in your code.

await Taplytics.start("JS_SDK_Key")
const variable = Taplytics.variable("JS String", "default")
console.log("variable value: ", variable.value)
// or
await Taplytics.waitForLoaded()
const variable = Taplytics.variable("JS String", "default")
console.log("variable value: ", variable.value)

It is also possible to pass an optional third argument into the Taplytics.variable method, which is a callback function. This function will be called with the correct variable value after the initial configuration has been loaded by the SDK.

If the configuration has already been loaded, the callback will be called immediately.
If the experiments fail to load, the callback will be called with the default value.

Taplytics.variable("JS String", "default", (value) => {
    console.log("variable value: ", value)
})

Note: New code variables added in code will be auto-created on the dashboard. To see and modify the code variables you've added in code on the dashboard, the SDK must be launched and the code accessing the variable must be executed at least once. You may manually create code variables on the dashboard as well.

Get Running Experiments

If you would like to see a list of all experiments and variations that are running, use the getRunningExperimentsAndVariations function. This will return a promise which resolves to the current experiments and their variations that the browser is receiving once the SDK has loaded the config from our servers.

The promise will resolve to an Object with experiment names as the keys, and variation names as the values. Example:

const expAndVars = await Taplytics.getRunningExperimentsAndVariations()
console.log("expAndVars", expAndVars)
// expAndVars {
//  "Experiment 1": "baseline",
//  "Experiment 2": "Variation 1"
//}

Note that this method will always wait for the SDK to finish any ongoing operations that may change the set of experiments.

For example, changing the user's identity will trigger a new configuration to be retrieved. Calling this method during that time will result in the promise waiting until the new configuration has been retrieved before returning the most up-to-date experiments.

Feature Flags

Taplytics feature flags are a way to easily enable or disable product features. Check whether a flag is enabled by passing its key into the featureFlagEnabled method, which will return a boolean:

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

If a feature flag is evaluated before the configuration as finished loading from Taplytics servers, it will default to false. In order to prevent this, you can ensure that the configuration is loaded before using the feature flag. This can be done by awaiting the start method, or the Taplytics.waitForLoaded method if Taplytics has already been started somewhere else in your code.

await Taplytics.start('YOUR TOKEN')
if (Taplytics.featureFlagEnabled("featureFlagKey")) {
    // Put feature code here, or launch feature from here
}

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

Get Running Feature Flags

If you would like to see a list of feature flags that are enabled on the browser, there exists a getRunningFeatureFlags function which returns a promise resolving to an object that contains the current enabled feature flags.

The promise will only resolve when Taplytics has finished loading the configuration from the server. The feature flags will be provided in an object where the keys are the feature flag key names and their corresponding values are the names of the associated feature flags.

const runningFF = await Taplytics.getRunningFeatureFlags()
console.log("runningFF", runningFF)
//    runningFF {
//        "featureFlagKey": "My First Feature Flag",
//        "key with spaces": "My Second Feature Flag"
//    }

Test Experiments and Feature Flags

To test/QA specific experiment and variation combinations, as well as feature flags,
use the test_experiments option with an Object containing keys of the Experiment or Feature flag names, and values of Variation names (or baseline).

For feature flags, just specify baseline as the variation

Taplytics.start("JS_SDK_TOKEN", {
    test_experiments: {
        "JS experiment": "Variation 1",
        "JS experiment 2": "baseline",
        "JS Feature Flag": "baseline"
    }
});

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.

start

Usage: Taplytics.start(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.

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.
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.start()` won't be used for segmentation until the next session.

Returns

(Object): Returns a promise which resolves when the configuration has been loaded from the server, or the request has timed out.

Example

// Without options
await Taplytics.start("JS_SDK_TOKEN");

// With some options
await Taplytics.start("JS_SDK_TOKEN", {
    log_level: 1
});

waitForLoaded

Usage: Taplytics.waitForLoaded()

Returns a promise which resolves when the initial experiment configuration has been retrieved from the server.

Returns

(Object): A promise that resolves when the SDK has finished its initial loading of the configuration.

Example

await Taplytics.waitForLoaded()

isLoaded

Usage: Taplytics.isLoaded()

Returns a boolean which indicates whether the initial configuration has been retrieved from the server.

Returns

(Object): A boolean with the value true if the SDK has finished its initial loading of the configuration, and false otherwise.

Example

const loaded = Taplytics.isLoaded()
if (!loaded) {
    // Taplytics isn't loaded yet!
}

setUserAttributes

Usage: Taplytics.setUserAttributes(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.

Setting a user_id will automatically cause a new session to be triggered and a new configuration to be loaded so there is no need to manually start a new session.

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] (string): User's first name (optional).
[user_attributes.lastName] (string): User's last name (optional).
[user_attributes.name] (string): 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 a promise which resolves when all necessary operations triggered by this call have completed.
If the user identity has stayed the same, this simply means the new properties have been saved. If the user identity has changed, the promise only resolves when a new configuration has been obtained for that user.

Example

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

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

logEvent

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

Tracks the occurrence of an event for the current visitor.

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.logEvent(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 nothing

Example

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

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

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

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

resetUser

Usage: Taplytics.resetUser()

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

Returns

(Object): Returns a promise which resolves when the reset operation has finished and the new configuration has been obtained
for the anonymous user.

Example

// Reset user
await Taplytics.resetUser();

getRunningExperimentsAndVariations

Usage: const expVars = await Taplytics.getRunningExperimentsAndVariations()

Returns a promise which resolves with an Object containing the running experiments and variation names when the SDK's configuration has loaded from Taplytics' servers.

If the SDK is in the process of retrieving a new configuration due to a user identity change, startNewSession call etc. then this call will wait until those operations have finished. This ensures the result is always the most up-to-date set of experiments for the currently identified user.

Example

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

getRunningFeatureFlags

Usage: const expVars = await Taplytics.getRunningFeatureFlags()

Returns a promise which resolves with an Object containing the enabled feature flag keys and names when the SDK's configuration has been loaded from Taplytics' servers.

Example

const expAndVars = await Taplytics.getRunningFeatureFlags()
// For example: 
// expAndVars = {
//  "featureKey1": "Feature Flag 1",
//  "featureKey22": "Feature Flag 2"
//};

variable

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

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.
[readyCallback] (function): Callback to be called when initial configuration has loaded from the server (optional).

Returns

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

Example

// Accessing a variable's value using the `readyCallback`
Taplytics.variable("JS String", "default", function(value) {
    console.log("JS String value: " + value);
});

// Accessing a variable's value directly after waiting for Taplytics to finish loading.
await Taplytics.start('YOUR TOKEN')
const syncVar = Taplytics.variable("JS String", "default");
console.log("JS String Sync value: " + syncVar.value);

applyVisualEdits

Usage: Taplytics.applyVisualEdits()

Applies Visual Editor Changes to the page whenever this is called. By default, this is automatically run during initialization of Taplytics. Use this if your contents load after Taplytics has already initialized.

Example

// Apply Visual Edits to page
Taplytics.applyVisualEdits()

trackClickGoals

Usage: Taplytics.trackClickGoals()

Attaches Instant Click Goals created via the Visual Web Editor to the elements on the page whenever this is called. By default this is automatically run during initialization of Taplytics. Use this if your contents load after Taplytics has already initialized.

Example

// Attach Instant Goals to elements
Taplytics.trackClickGoals()

New Session Callback

Usage: Taplytics.on('newSession', [newSessionCallback])

Registers a callback to be called whenever a new session is started. This can happen as a result of the session expiring, the user's identity changing, or the Taplytics.startNewSession() method being manually called.

Example

Taplytics.on('newSession', () => {
    console.log('New Taplytics Session Started');
})

Cookies

Below you'll find the Cookies that Taplytics is setting for session tracking, bucketing and identification purposes.

Name	Description
_tl_auid	Taplytics App User identifier
_tl_csid	Taplytics Cookie Session identifier
_tl_duuid	Taplytics Device identifier
_tl_sid	Taplytics Session identifier
_tl_uid	Taplytics user_id
_tl_config	Taplytics Cached Config

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

📘JavaScript SDK Update

Getting Started

1. Installation

i) NPM Module

ii) Using the CDN

Pin SDK version

Start Options

Caching & SDK Timeouts

2. Usage

3. Identify Users

4. Track Events

5. Experiments and Feature Flags

6. Opt-In/Out

7. Integrations

Adobe

Amplitude

Google Analytics

Mixpanel

MParticle / Segment

Extra Start Options

8. Adblockers: How to Navigate

Custom Domain Proxy

CNAME Aliasing

Using a Reverse Proxy

Sessions

Start New Session

Experiments

Dynamic Variables

Get Running Experiments

Feature Flags

Get Running Feature Flags

Test Experiments and Feature Flags

Reference

start

waitForLoaded

isLoaded

setUserAttributes

logEvent

resetUser

getRunningExperimentsAndVariations

getRunningFeatureFlags

variable

applyVisualEdits

trackClickGoals

New Session Callback

Cookies

Enable the Visual Editor

Making Visual Edits

📘
JavaScript SDK Update