Javascript SDK — Reference

Here are the APIs that Taplytics.js exposes:

Function Description
init Initializing Taplytics.js
identify Identifying the user
track Tracking events
page Tracking page views
reset Reseting User
propertiesLoaded Taplytics properties loaded
runningExperiments Taplytics running experiments
variable Taplytics variable
codeBlock Taplytics code block

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


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.

  1. token (string): Taplytics JS SDK
  2. [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 will be set as, that will also work on another subdomain such as: | | 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. |


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


// Without options

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


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.

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

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


// With just a few named user attributes

    email: "",
    age: 23,
    gender: "male",
    firstName: "Nima",
    lastName: "Gardideh"

// With non-named custom attributes

    user_id: 1015,
    loyalty_group: "very_loyal",
    purchases_count: 15,
    friends_Count: 800


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.


This function can also be called as follows:

Taplytics.track(event_name, [event_attributes])

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

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


// 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


Usage:[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.


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

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

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


// Track a page view with no attributes;

// Track it by setting a name"Page Name");

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

// Track a page view with a name and attributes"Shirts Page", {
    products_count: 150

// Track a page view with a name, a category, and attributes"Product Listings", "Shirts", {
    products_count: 150


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.


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


// Reset user



Usage: Taplytics.propertiesLoaded([callback])

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

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

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


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.

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

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


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

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

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

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


// 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);


Usage: Taplytics.codeBlock(name, codeBlock)

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

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

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