Activate

After successfully instantiating a VWO class, Activate API activates a FullStack A/B test for a specified user for a running campaign.

📘

Note

This API is applicable only to FullStack A/B campaigns only. This API will not activate a Feature Rollout or a Feature Test campaign when invoked with the corresponding campaign key,

Description

The API method:

• Validates the parameters passed.
• Checks whether the user is whitelisted.
• Checks if User Storage Service is provided to know whether the user is returning. If yes, show the previously assigned variation always.
• Checks if the campaign is part of Mutually Exclusive Group and evaluates all the grouped campaigns to decide whether the user is eligible for the campaign.
• Checks whether the user is eligible for a campaign based on pre-segmentation conditions.
• Checks whether the user qualifies to become a part of the campaign based on traffic allocation.
• Assigns a deterministic variation to the qualified user.
• Sends an impression event to the VWO server for generating reports.

The API method requires a campaign unique-key campaignKey and a User ID - userId. You can also pass other flags in the options key.

campaignKey is the required key provided at the time of FullStack campaign creation.
userId is the required unique id associated with the user for identification.
options is the optional key to provide targeting, whitelisting, User Storage Service stored data, and other flags based on your campaign setup and requirements.

The API method has various levels of stages and depending on each stage result, the subsequent stage is executed.

• Parameter Validation - first, validates the parameters passed. If these are not valid, log the error, and the API method returns null, that is, no variation found.
• Whitelisting - checks whether a user is forced into a variation. This could be achieved via user ID or passing custom variation targeting variables that would be evaluated against conditions configured inside the campaign on the VWO app. If the user is whitelisted, variation defined in conditions is returned otherwise proceeded further.
• Pre-segmentation - checks whether the user passes the segmentation conditions i.e. whether the user is eligible for the campaign by evaluating campaign segmentation conditions against passed custom variables. If the user is eligible, then proceed further, otherwise return.
• User Bucketing - checks whether the User(userId) qualifies for the campaign. This is achieved by hashing the userId by using the murmur3 hashing algorithm, which always provides the same hash value for the same userId. This helps in maintaining consistent behavior throughout for a particular userId. The hash value is normalized to a number in the range 1–100 and is checked with the campaign percent traffic, which was configured at the time of campaign creation. If the hash value is less than or equal to the campaign percent traffic, the user is marked as being qualified for the campaign having test-key as campaignKey. If the userId is not qualified for the campaign, the API method returns null, that is, no variation assigned.
• Variation Assignment - assigns a variation to the userId after the user is qualified for the campaign, which again uses the murmur3 hashing algorithm and evenly distributes the traffic based on the traffic distribution of each variation that was configured at the time of campaign creation. The API method returns the name of the assigned variation.
  This method does take care of UserStorageService. It first looks into UserStorageService(if provided at the time of Instantiation) before the above logic executes and if the stored variation is found, it returns with that variation name.
• Sending Impression - sends an asynchronous impression to the VWO server for generating reports.

Parameter definitions

Returns

The name of the variation in which the user is bucketed, or null if the user doesn't qualify to become a part of the campaign.

Usage

// campaignKey: you provide at the time of campaign creation
// userId: how you identify a particular user
// options: (Optional)
//   customVariables: pre-segmentation variables
//   variationTargetingVariables: forced variation variables
//.  userAgent: userAgent of visitor to use segmentation on VWO
//   userIpAddress: IpAddress of visitor to use segmentation on VWO

var options = {
  customVariables: {},
  variationTargetingVariables: {},
  userAgent: '',
  userIpAddress: ''
};
var variation = vwoClientInstance.activate(campaignKey, userId, options);

if (variation === 'Control') {
  // Write code for handling 'Control'
} else if (variation === 'Variation-1') {
  // Write code for handling 'Variation-1'
} else {
  // CODE: User is not qualified for the campaign. Would be due to configuring campaign's percent-traffic less than 100% while creating or updating a FullStack campaign.
}

For passing userStorageData in the options, please follow this doc.

Unique Visitors are tracked

If User Storage Service is provided, SDK will not track the same visitor multiple times. Once tracked and stored by the User Storage Service, the next time the same visitor lands, it will check the existence from the storage via User Storage Service. If found, it will not track the same visitor.

🚧

Unique Visitors

VWO only tracks a visitor and its corresponding conversion only once even if the SDK sends multiple calls.

When is Campaign Activation Mandatory

If User Storage Service is provided, campaign activation is mandatory before tracking any goal, getting a variation of a campaign, and getting the value of the feature's variable.

Passing meta-information that would be available to User Storage Service

If User Storage Service is provided, there could be cases where you would want to store some other details along with the VWO decision-related data into the storage. It is easily achievable by storing the data at your end asynchronously, while SDK will use the User Storage Service to save the decision-related data.
Our SDKs provide a way of passing the meta-information like browser, os, IP address, location, etc., along with the decision-related data. The data you will provide in the API call will be available in the set method of User Storage Service, which you can use to save along with VWO SDK's decision-related data.

var vwoSDK = require('vwo-node-sdk');

var userStorageService = {
  get: function (userId, campaignKey) {
    // Get stored user-campaign data mapping in the format sdk passed it to set method
  },
  set: function (data) {
    // Save user-campaign data mapping
    // Access meta-data as data.metaData
  }
};

var vwoClientInstance = vwoSDK.launch({
  settingsFile: settingsFile,
  userStorageService: userStorageService 
});

const options = {
  metaData: {
    browser: 'chrome',
    os: 'linux'
  }
};

vwoClientInstance.activate(campaignKey, userId, options);

🚧

Note

Passing meta-information is available from v1.13.0 onwards

Promises and async

If your application uses promises for asynchronous operations, you can configure the SDK to manage asynchronous operations. VWO SDK is capable of returning a value as well as promise depending on the use case.
When returning a value, API response time is faster (< 50ms) as it does not wait for the asynchronous tracking call to get completed. in the case of returning a promise, API will wait for both the decision as well as the asynchronous tracking call to get completed, and thereby, the response time of the API will include the round-trip time of the network call.

Since the async/await syntax is based on Promises, all APIs will also work with it.

Configuring the SDK

You can pass returnPromiseFor option at the time of instantiating the SDK i.e. while using launch API.
The returnPromiseFor option is an object and you can use it either to enable promise-based response from all the APIs or select the required API(s).

const vwoInstance = vwoSdk.launch({
  settingsFile,
  returnPromiseFor: {
    all: true
  }
});

// Or just for activate API

const vwoInstance = vwoSdk.launch({
  settingsFile,
  returnPromiseFor: {
    activate: true
  }
});

Example

// Using the .then() method to add a handler for a Promise
vwoClientInstance.activate(campaignKey, userId).then(variationName => {
  // use variationName in your application code
});

// Using "await" instead, within an async function
const variationName = await vwoClientInstance.activate(campaignKey, userId);