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

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

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

return a Flagship instance.

Demo:

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

Flagship class

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

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((normalModeResponse) => {
    // do something...
  });

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, normal or simple mode depending on value of fetchMode argument.

Demo:

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

getModifications

return an 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 */)

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

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.