Flagship - JS SDK

Prerequisites

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

• Npm: version 3.0.0 or later...

Good to know

- Typescript supported ✅

- Light weight SDK 🏋 (Gzipped size=38KB~)

- How to use the SDK in practice ☕ :
• with React
  • 👉online demo 😎
• with Express

- Release notes available to stay in touch 👍

Getting Started

• Install the node module:

npm install @flagship.io/js-sdk

• Then import it in your code :

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

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

• Then initialize:

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

• Then create a visitor:

const visitorInstance = sdk.newVisitor("YOUR_VISITOR_ID",{
    //...
    some: "VISITOR_CONTEXT",
    //...
});

visitorInstance.on('ready', () => {
    console.log('visitorInstance is ready ! ✨')
});

• Then get modifications:

visitorInstance.getModifications([{key: "btnColor", defaultValue: "#ff0000"}, {key: "btnText", defaultValue: "Wahoo !"}])
.then(({btnColor, btnText}) => {
  // do some stuff
  myButton.setColor(btnColor);
  myButton.setText(btnText);
})

• Or even better, if you fetched campaigns already before (during initialization as example):

const {btnColor, btnText} = visitorInstance.getModificationsCache([{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. 🙂

SDK Settings

This is all available settings which you can set on the SDK.

Those settings can be setup using initSdk function (sample inside).

Here are the attributes which you can set inside the SDK settings object:

JS SDK Features

Don't hesitate to have a look to the main Flagship technical doc as well 😊.

flagshipSdk object

• initSdk

Flagship class

• newVisitor

FlagshipVisitor class

• setContext
• synchronizeModifications
• getAllModifications
• getModificationsForCampaign
• getModifications
• activateModifications
• getModificationsCache
• sendHits

Shape of possible hits to send

• Transaction Hit
• Screen Hit
• Item Hit
• Event Hit

flagshipSdk object

initSdk

return a Flagship instance.

Demo:

const sdk = flagship.initSdk("YOUR_ENV_ID",
{
    enableConsoleLogs: true,
    fetchNow: false,
});

Flagship class

• newVisitor

newVisitor

return a FlagshipVisitor instance.

Demo:

const visitorInstance = sdk.newVisitor("YOUR_VISITOR_ID",{
    //...
    some: "VISITOR_CONTEXT",
    //...
});

visitorInstance.on('ready', () => {
    console.log('visitorInstance is ready ! ✨')
});

FlagshipVisitor class

• setContext
• synchronizeModifications
• getAllModifications
• getModificationsForCampaign
• getModifications
• getModificationsCache
• sendHits

setContext

edit the context of the visitor

return nothing

Demo:

const visitorInstance = sdk.setContext({
    //...
    some: "NEW_VISITOR_CONTEXT",
    //...
});

synchronizeModifications

return a Promise<number>

Add/update all modifications data which are in cache. Might be useful when your visitor instance has been initialized a while ago and some change have been done on Flagship platform meanwhile. From there some modifications may have changes, so calling synchronizeModifications make sure everything is fine. 😃

It returns a number (=response status code) when promise is resolved.

Demo:

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

getAllModifications

return an Promise<object> which contains all data for all campaigns which the visitor can have

The shape of the object look like same as decision api response, normal mode.

Demo:

visitorInstance.getAllModifications()
  .then((response) => {
    // do something...
  });

with the following data:

// response.data gives this kind of shape:
{
  visitorId: 'VISITOR_ID',
  campaigns: [
    {
      id: 'CAMPAIGN_ID',
      variationGroupId: 'VARIATION_GROUP_ID',
      variation: {
        id: 'VARIATION_ID',
        modifications: {
          type: 'FLAG',
          value: {
            btnColor: '#fff',
          },
        },
      },
    },
    // {...}
  ]
}

getModificationsForCampaign

return a promise<object> which contains the data for a specific campaign

The shape of the object look like same as decision api response.

Demo:

visitorInstance.getModificationsForCampaign()
  .then((response) => {
    // do something...
  });

with the following data:

// response.data gives this kind of shape:
{
  visitorId: 'VISITOR_ID',
  campaigns: [
    {
      id: 'CAMPAIGN_ID',
      variationGroupId: 'VARIATION_GROUP_ID',
      variation: {
        id: 'VARIATION_ID',
        modifications: {
          type: 'FLAG',
          value: {
            btnColor: '#fff',
          },
        },
      },
    },
    // {...}
  ]
}

getModifications

return a Promise<object> where each key is a modification with corresponding value

The data returned will be the data from all modifications that you specify in the modificationsRequested argument

Demo:

visitorInstance.getModifications([
    {
        key: "btnColor", // required
        defaultValue: "#ff0000", // required
        activate: true // optional
    },
    {
        key: "customLabel", // required
        defaultValue: "Flagship is awesome", // required
    }
], /* ActivateAllModifications */)
.then(({btnColor, customLabel}) => {
  // do some stuff
})
.catch((error) => {
  // error :(
})

will return:

// modifications shape:
{
  btnColor: '#dcbc02',
  customLabel: 'Flagship is awesome' // default value set (ie: no campaigns have specified this modification)
}

activateModifications

return nothing (for the moment...)

Kind of same behavior as getModifications. It will activate the first campaign in cache that's matching the key set in argument. If conflict exist, you'll be notified via warning logs (+ debug logs if need details)

Demo:

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

will produce following behaviour:

scenario 1:

Assuming the api gives those informations 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 api gives those informations 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 api gives those informations 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 logs a conflict for modification customLabel as it is considered as it is not supposed to happen.

getModificationsCache

return an object where each key is a modification with corresponding value

Same behavior as getModifications function but without returning a promise.

NOTE: You need to fetch modifications to automatically save them in cache. You can achieve it using synchronizeModifications or fetchNow=true.

Demo:

visitorInstance.getModificationsCache([
    {
        key: "btnColor", // required
        defaultValue: "#ff0000", // required
        activate: true // optional
    },
    {
        key: "customLabel", // required
        defaultValue: "Flagship is awesome", // required
    }
], /* ActivateAllModifications */)

will return:

{
  btnColor: '#dcbc02',
  customLabel: 'Flagship is awesome' // default value set (ie: no campaigns have specified this modification)
}

sendHits

return a Promise<void>

This function allow you to send any kind of hit. All details of each hit below 👇.

Demo:

visitorInstance.sendHits(
    [
        {
            type: 'Screen',
            data: {
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "yoloScreen"
            }
        },
        {
            type: 'Event',
            data: {
                category: 'User Engagement',
                action: 'signOff',
                label: 'Hello world',
                value: 123,
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "yoloEvent"
            }
        },
        {
            type: 'Item',
            data: {
                transactionId: '0987654321',
                name: 'yoloItem',
                price: 999,
                code: 'yoloCode',
                category: 'yoloCategory',
                quantity: 123,
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "yoloItem"
            }
        },
        {
            type: 'Transaction',
            data: {
                transactionId: '1234567890',
                affiliation: 'yoloAffiliation',
                totalRevenue: 999,
                shippingCost: 888,
                shippingMethod: 'yoloShippingMethod',
                currency: 'yoloCurrency',
                taxes: 1234444,
                paymentMethod:'yoloPaymentMethod',
                itemCount: 2,
                couponCode: 'YOLOCOUPON',
                documentLocation: "http%3A%2F%2Fabtastylab.com%2F60511af14f5e48764b83d36ddb8ece5a%2F",
                pageTitle: "yoloTransaction"
            }
        },
    ]
).then(() => console.log('All hits send !')

Shape of possible hits to send

• Transaction Hit
• Screen Hit
• Item Hit
• Event Hit

Transaction Hit

Screen Hit

Item Hit

Event Hit

Contributing

Take a look to the Contributors Guide.

What is Flagship ?

Have a look here.

License

Flagship uses license under the Apache version 2.0.