JavaScript, Node, Deno V2.2.X

Introduction

SDK overview

The following documentation will help you get Flagship running in your JavaScript environment (client-side or server-side) with preconfigured methods to implement the Decision API.

Feel free to contact us if you have any questions regarding this documentation.

SDK features

This SDK version helps you:

• Set a visitor ID
• Update user context
• Assign campaigns via the Decision API or via the Bucketing
• Get modifications
• Activate campaigns
• Send hits to our Universal Collect

Prequisites

• Node.js: version 6.0.0 or later
• Npm: version 3.0.0 or later

Good to know

• Latest Version
• Github repository
• Gzipped size:
• SDK runnable on both client-side and server-side
• Typescript code supported
• Open-source demos available using the SDK

Changelog

• Visible on Github

Getting started

Initialization

There are five steps to follow to get started with the JS/NodeJS Flagship SDK:

1. Install the node module

npm install @flagship.io/js-sdk

2. Import it in your code

import flagship from "@flagship.io/js-sdk"; // ES6 ++

const flagship = require("@flagship.io/js-sdk"); // ES5

3. Initialize

const fsInstance = flagship.start("YOUR_ENV_ID", "YOUR_API_KEY", {
  /* sdk settings */
});

4. Create a visitor

const fsVisitorInstance = fsInstance.newVisitor("YOUR_VISITOR_ID", {
  some: "VISITOR_CONTEXT",
});

5. When the visitor is ready, get modifications

fsVisitorInstance.on("ready", ({ withError, error }) => {
  if (withError) {
    console.error("Ouch, visitor is ready but with error : " + error.stack);
  } else {
    console.log("visitor is ready without error ! ✨");
  }

  const { btnColor, btnText } = fsVisitorInstance.getModifications([
    {
      key: "btnColor",
      defaultValue: "#ff0000",
    },
    {
      key: "btnText",
      defaultValue: "Wahoo !",
    },
  ]);

  console.log(btnColor); // output: "#fff"
  console.log(btnText); // output: "Awesome !"
});

This is one of the basic workflow you can achieve with the SDK. 🙂

API Reference

start function

To run experiments with Flagship, you will need to start the SDK. Flagship uses a Flagship instance that can activate experiments and track events.

Use the following code returns a Flagship instance:

import flagship from "@flagship.io/js-sdk";

const fsInstance = flagship.start("YOUR_ENV_ID", "YOUR_API_KEY", {
  enableConsoleLogs: true,
  // other settings...
});

SDK settings

Here are all available settings you can set on the SDK.

Those settings can be setup using start function.

Below the attributes you can set inside the SDK settings object:

Flagship class

• newVisitor
• startBucketingPolling
• stopBucketingPolling

newVisitor function

Demo:

const myVisitorContext = { some: "VISITOR_CONTEXT" };

const fsVisitorInstance = fsInstance.newVisitor("YOUR_VISITOR_ID", {
  ...myVisitorContext,
});

// OR with auto-gen id

const fsVisitorInstance = fsInstance.newVisitor(null, { ...myVisitorContext });

📘

Be aware that on client side and when you do not specify a visitor id, as enableClientCache is enable by default, the SDK will try to find a previous visitor experience. If so, the new visitor will have the same visitor id as it was during the previous visitor session. From there, no id will be automatically generated.

Calling newVisitor will create and return a FlagshipVisitor instance.
Following the visitor initialization, you must listen the ready listener to ensure asynchronous processes inside the SDK are finished.

fsVisitorInstance.on("ready", ({ withError, error }) => {
  if (withError) {
    console.error("Ouch, visitor is ready but with error : " + error.stack);
  } else {
    console.log("visitor is ready without error ! ✨");
  }
});

newVisitor function takes the following arguments:

ready listener expose in argument an object containing those attributes:

startBucketingPolling function

Demo:

const fsInstance = flagship.start("ENV_ID", "API_KEY", {
  fetchNow: false,
  decisionMode: "Bucketing",
  pollingInterval: 5 /*, other settings...*/,
});

// do some stuff...

fsInstance.startBucketingPolling();

Start the Bucketing behavior. The Bucketing won't restart if you call this function multiple times.

Return an object with following shape { success: boolean; reason?: string }.

stopBucketingPolling function

Demo:

const fsInstance = flagshipSdk.start("ENV_ID", "API_KEY", {
  fetchNow: false,
  decisionMode: "Bucketing",
  pollingInterval: 5 /*, other settings...*/,
});

// do some stuff...

fsInstance.startBucketingPolling(); // start manually the bucketing (as fetchNow is equal to "false")

setTimeout(() => fsInstance.stopBucketingPolling(), 100 * 1000); // stop bucketing 100 seconds later...

Stop the Bucketing behavior. If you call this function multiple times, you will see a log notifying that it's already stopped.

Return an object with following shape { success: boolean; reason?: string }.

FlagshipVisitor class

• Event listeners
• updateContext
• synchronizeModifications
• getModifications
• getAllModifications
• getModificationsForCampaign
• getModificationInfo
• activateModifications
• sendHit
• sendHits
• authenticate
• unauthenticate

Event listeners

The FlagshipVisitor includes event listeners to help you handle the SDK.

To listen once:

fsVisitorInstance.once("ready", () => {
  console.log("Flagship SDK is ready!");
});

To listen anytime:

fsVisitorInstance.on("saveCache", (args) => {
  const {
    modifications: { after },
  } = args;
  console.log(
    "Flagship SDK will save in cache those modifications:\n" +
      JSON.stringify(after)
  );
});

The saveCache listener has an argument in the callback with the following shape:

❗️

Before using any function from FlagshipVisitor, it is important that you have listened the ready event to ensure everything is working properly and your visitor is up to date with campaigns assignment.

updateContext function

The visitor context is a property dataset which defines the current user of your app. This dataset is used as targeting criteria for campaign assignment.

Use the updateContext function to modify the value of existing attributes or add new attributes entirely:

const fsVisitorInstance = fsInstance.updateContext({
  //...
  some: "NEW_VISITOR_CONTEXT",
  //...
});

The function takes the following arguments:

🚧

Updating the context does not automatically activate campaigns matching this new context. To do so, you must manually call the synchronizeModifications function.

synchronizeModifications function

See the demo

The synchronizeModifications function updates campaigns targeting that match the current visitor context.

When in decisionMode="API", it will also refreshes all modification data in cache by making a new call to the Flagship decision API.

It returns a Promise<number> where number is the response status code when the promise is resolved.

The function takes the following arguments:

getModifications function

See the demo

The getModifications function returns the data from all modifications that you specify in the modificationsRequested argument.

Each element of the modificationsRequested array argument follows this object structure:

📘

This method loads modifications from cache. To save modifications automatically in cache, you need to retrieve them using synchronizeModifications or fetchNow=true.

If the cache is empty, getModifications function will always return default values.

getAllModifications function

See the demo

The getAllModifications method returns a Promise<object> containing all the data for all the campaigns associated with the current visitor.

The object resolved by the promise has the same shape as the Decision API response (normal mode).

The function takes the following arguments:

getModificationsForCampaign function

See the demo

Useful to request the data for a specific campaign.

The function takes the following arguments:

getModificationInfo function

Using the getModificationInfo function allows you to specify a key in the argument. It returns an object with information about the modification that matches the specified key.

fsVisitorInstance
  .getModificationInfo("myKey")
  .then((response) => {
    // do some stuff...
  })
  .catch((error) => {
    // something is going wrong...
  });

The example above returns a Promise<object | null>. (Typescript: GetModificationInfoOutput)

The response can either be null (when the modification does not exist) or either be an object with following shape:

{
  campaignId: 'CAMPAIGN_ID',
  variationGroupId: 'VARIATION_GROUP_ID',
  variationId: 'VARIATION_ID',
}

The function takes the following arguments:

📘

If the key matches more than one campaign, it will return information for the first campaign that the Flagship SDK has in its campaigns cache.

activateModifications function

See the demo

It activates the first campaign in cache that matches the key specified in the argument.

This function returns nothing and takes following argument:

Each element of the array follow this object structure:

📘

In case of any conflicts, you'll be notified via warning logs (or debug logs if you need more details).

sendHit function

Demo:

fsVisitorInstance.sendHit(
  {
    type: 'Screen',
    data: {
        documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
        pageTitle: "testScreen"
  }
).then(() => console.log('Hit send !')

The sendHit function lets you to send any type of hit.

Returns a Promise<void> and has following argument:

sendHits function

Demo:

fsVisitorInstance.sendHits(
    [
        {
            type: 'Screen',
            data: {
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "testScreen"
            }
        },
        {
            type: 'Event',
            data: {
                category: 'User Engagement',
                action: 'signOff',
                label: 'Hello world',
                value: 123,
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "testEvent"
            }
        },
        {
            type: 'Item',
            data: {
                transactionId: '0987654321',
                name: 'testItem',
                price: 999,
                code: 'testCode',
                category: 'testCategory',
                quantity: 123,
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "testItem"
            }
        },
        {
            type: 'Transaction',
            data: {
                transactionId: '1234567890',
                affiliation: 'testAffiliation',
                totalRevenue: 999,
                shippingCost: 888,
                shippingMethod: "DHL",
                currency: "USD",
                taxes: 1234444,
                paymentMethod: "creditCard",
                itemCount: 2,
                couponCode: 'TESTCOUPON',
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "testTransaction"
            }
        },
    ]
).then(() => console.log('All hits send !')

The sendHits function allow you to send multiple hits of any type in a single request:

Returns a Promise<void> and has following argument:

authenticate function

See the demo

Tells the SDK that the visitor is switching from an anonymous to an authenticate state by changing its visitor id and ensure that it's keeping the same experience (= same modifications).

This function returns a Promise<void> (asynchronous behavior) and takes following argument:

unauthenticate function

See the demo

Tells the SDK that the visitor is switching from an authenticate to an anonymous state. Under the hood, it will set back the initial id (anonymous) that was set during visitor initialization and this will ensure that it's keeping the same experience (= same modifications).

This function returns a Promise<void> (asynchronous behavior) and doesn't have any argument.

🚧

unauthenticate function will return an error if you didn't called authenticate function before.

Getting modifications

with getModifications

Click here for details on getModifications

const getModificationsOutput = fsVisitorInstance.getModifications(
  [
    {
      key: "btnColor", // required
      defaultValue: "#ff0000", // required
      activate: true, // optional ("false" by default)
    },
    {
      key: "customLabel", // required
      defaultValue: "Flagship is awesome", // required
    },
  ] /* ActivateAllModifications */
);

From there, getModificationsOutput will have:

// Note that for each modification key, the value depends on if your visitor is matching corresponding campaign or not.
{
  btnColor: '#dcbc02',
  customLabel: 'Flagship is awesome' // default value set (ie: no campaigns have specified this modification)
}

with getAllModifications

Click here for details on getAllModifications

fsVisitorInstance.getAllModifications().then((response) => {
  // Do something
});

The response includes the following data:

{
  visitorId: 'VISITOR_ID',
  campaigns: [
    {
      id: 'CAMPAIGN_ID',
      variationGroupId: 'VARIATION_GROUP_ID',
      variation: {
        id: 'VARIATION_ID',
        modifications: {
          type: 'FLAG',
          value: {
            'MODIFICATION_KEY': 'MODIFICATION_VALUE',
          },
        },
      },
    },
    // {...}
  ]
}

with getModificationsForCampaign

Click here for details on getModificationsForCampaign

fsVisitorInstance.getModificationsForCampaign().then((response) => {
  // Do something
});

The response includes the following data:

{
  visitorId: 'VISITOR_ID',
  campaigns: [
    {
      id: 'CAMPAIGN_ID',
      variationGroupId: 'VARIATION_GROUP_ID',
      variation: {
        id: 'VARIATION_ID',
        modifications: {
          type: 'FLAG',
          value: {
            'MODIFICATION_KEY': 'MODIFICATION_VALUE',
          },
        },
      },
    },
    // {...}
  ]
}

Campaign synchronization

with synchronizeModifications

Click here for details on synchronizeModifications

fsVisitorInstance
  .synchronizeModifications()
  .then((statusCode) =>
    console.log(
      `synchronizeModifications responded with status code:${statusCode}`
    )
  );

Campaign activation

Campaign activation tells Flagship Decision API that modifications have been applied to your visitor.

with activateModifications

Click here for details on activateModifications

fsVisitorInstance.activateModifications([
  {
    key: "btnColor", // required
  },
  {
    key: "customLabel", // required
  },
]);

The code above will yield one of the following behaviors:

• Scenario 1

  Assuming the Decision API returns the campaign information in the following order:

  • Modification btnColor is in campaign campaignA
  • Modification customLabel is in campaign campaignB

  Both campaignA and campaignB will be activated

• Scenario 2

  Assuming the Decision API returns the campaign information in the following order:

  • Modification btnColor and customLabel is in campaign campaignA
  • Modification customLabel is in campaign campaignB

  Only campaignA will be activated

• Scenario 3

  Assuming the Decision API returns the campaign information in the following order:

  • Modification customLabel is in campaign campaignA
  • Modification btnColor and customLabel is in campaign campaignB

  Both campaignA and campaignB will be activated, but the SDK will log a conflict for the customLabel modification considering this scenario is not supposed to happen.

Experience continuity

It might happen that a visitor from your app is not yet recognized and is being authenticated (and recognized) later on...

From there, we provide the ability to ensure that during such transition, your visitor will keep the same experience (meaning targetting still the same campaign's variations and thus the same modifications).

In order to do a successful experience continuity, we will have to distinguish when the visitor is anonymous or authenticated.

Let's assume basic scenario to understand how things work:

1. Your visitor arrives on your app for the first time.

We need to initialize the visitor but as we don't known anything about this visitor, we'll create a random visitor id or let the SDK do it for us. You can also specify some visitor context if necessary.

visitorInstance = sdk.newVisitor(null, { ...someVisitorContext });

visitorInstance.on("ready", () => {
  console.log("visitor with new experience is ready ! ✨");
});

We put null in the first argument so the SDK has auto-created an id for our visitor.

Whatever how it has been set, the actual visitor id will be what we call its anonymous id.

2. Your visitor is signing in.

To tell the SDK about this change, you'll have to call authenticate function which takes a visitor id as argument.

The visitor id set in argument is required and should be an existing visitor id (that has previously seen specific campaign's modifications) in order to make the experience continuity effective.

await visitorInstance.authenticate("VISITOR_ID_ALREADY_KNOWN_BY_FLAGSHIP");

// OR

visitorInstance
  .authenticate("VISITOR_ID_ALREADY_KNOWN_BY_FLAGSHIP")
  .then(() => console.log("visitor successfully updated."));

This new visitor id is what we call its authenticated id.

The visitor is updated as authenticated, keeping the previous variations from campaigns that are still matched and thus gives you same modifications as before being logged in.

📘

Keep in mind that if the visitor also has its context changed, you might still have changes on modifications as your visitor might target new campaigns.

3. Your visitor decide to sign out.

If you want to keep the same visitor experience, then you should do:

await visitorInstance.unauthenticate();

// OR

visitorInstance
  .unauthenticate()
  .then(() => console.log("visitor successfully updated."));

If for some reason you decide to deliver a new visitor experience, you should create a new visitor instead:

const newVisitorInstance = fsInstance.newVisitor(null, {
  ...someVisitorContext,
});

fsVisitorInstance.on("ready", () => {
  console.log("visitor with new experience is ready ! ✨");
});

Hit tracking

This section helps you track your users in your application and learn how to build hits in order to feed campaign goals. For more information about our measurement protocol, read our Universal Collect documentation.

There are four different types of hits available:

• Screen
• Page
• Transaction
• Item
• Event

Screen

Demo:

fsVisitorInstance.sendHit(
        {
            type: 'Screen',
            data: {
                documentLocation: "Home page",
            }
        }
).then(() => console.log('Screen hit send !')

Page

Demo:

fsVisitorInstance.sendHit(
        {
            type: 'Page',
            data: {
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
            }
        }
).then(() => console.log('Page hit send !')

Transaction

Demo:

fsVisitorInstance.sendHit(
        {
            type: 'Transaction',
            data: {
                transactionId: '1234567890',
                affiliation: 'testAffiliation',
                totalRevenue: 999,
                shippingCost: 888,
                shippingMethod: "DHL",
                currency: "USD",
                taxes: 1234444,
                paymentMethod: "creditCard",
                itemCount: 2,
                couponCode: 'TESTCOUPON',
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "testTransaction"
            }
        }
).then(() => console.log('Transaction hit send !')

Item

Demo:

fsVisitorInstance.sendHit(
        {
            type: 'Item',
            data: {
                transactionId: '0987654321',
                name: 'testItem',
                price: 999,
                code: 'testCode',
                category: 'testCategory',
                quantity: 123,
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "testItem"
            }
        }
).then(() => console.log('Item hit send !')

📘

The ITEM hit isn't available yet in the Flagship reporting view.

Event

Demo:

fsVisitorInstance.sendHit(
        {
            type: 'Event',
            data: {
                category: 'User Engagement',
                action: 'signOff',
                label: 'Hello world',
                value: 123,
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "testEvent"
            }
        }
).then(() => console.log('Event hit send !')

Demos

Code sandbox using Express JS

Live Demo 🕹

Node JS using Express JS

Readme 📖

[Deprecated] React app

Readme 📖

Live Demo 🕹

Appendix

Release note

Take a look to the Release note.

Contributing

Take a look at the Contributors Guide if you're interested in contributing to the SDK.

License

This Flagship SDK is distributed under the Apache version 2.0 license.