Developer Documentation
Guides

Quick-start

Suggest Edits

Installation

Refer to the installation page for installation steps.

Flagship Usage

Start SDK

Step 1: Start the SDK by importing the Flagship class from @flagship.io/js-sdk package for NodeJs or https://deno.land/x/flagship_io_js_sdk/mod.ts for Deno. Then, call the static function start.

This function should be called once at an appropriate location in your application.

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

Flagship.start("<ENV_ID>", "<API_KEY>");

import { Flagship } from "https://deno.land/x/flagship_io_js_sdk/mod.ts";

Flagship.start("<ENV_ID>", "<API_KEY>");

This starts the SDK in DECISION-API. More options are available in the SDK configuration.

👍

Good to know

Your apiKey and environmentId can be found in your Flagship account under Parameters > Environment & Security.

Create a visitor

Step 2: Create a visitor using the newVisitor method from the Flagship instance. The visitor instance allows you to set relevant data for Flagship to make a decision, including: Visitor ID, Visitor Context, GDPR Consent, and Authentication status.

For example, if you want to enable a specific feature for all your VIP visitors, you'll need to add this data as an attribute into the visitor context (key-value pair): isVIP: true. Based on your targeting criteria defined in your use-case (isVIP === true), Flagship will make the decision and show your feature to visitors that have isVIP in their context and for which isVIP is equal to true.

// ...import code 

Flagship.start("<ENV_ID>", "<API_KEY>");

const fsVisitor = Flagship.newVisitor({
  visitorId: "<VISITOR_ID>",
  hasConsented: true, // this is required
  context: {
    isVIP: true,
    country: "NL",
    loginProvider: "Google"
  }
});

Getting Flags

Steps 3, 4, and 5 involve fetching flags from Flagship, retrieving your flag, and reading your flag's value.

First, fetch flags from the Flagship platform using the fetchFlags method. You can ensure that your flags are fetched and ready to be used by using an await statement, a then function, or an event listener.

Then, use the getFlag method of the visitor instance to retrieve a specific flag object based on the key provided. This object includes methods to retrieve the flag value, access flag metadata, expose the flag, verify the flag's existence, and get the flag status.

// Retrieving flags with an 'await' statement
//...import code

// Step 1: start the SDK
Flagship.start("your_env_id", "your_api_key");

//Step 2: Create a visitor
const visitor = Flagship.newVisitor({
  visitorId: "your_visitor_id",
  context: { isVip: true },
});

//Step 3: Fetch flag from the Flagship platform 
await visitor.fetchFlags();

// Step 4: Retrieves a flag named "displayVipFeature"
const flag = visitor.getFlag("displayVipFeature");

//Step 5: Returns the flag value ,or if the flag does not exist, it returns the default value "false"
console.log("flag value", flag.getValue(false))

// Retrieving flags with a 'then' function
//...import code

// Step 1: start the SDK
Flagship.start("your_env_id", "your_api_key");

//Step 2: Create a visitor
const visitor = Flagship.newVisitor({
  visitorId: "your_visitor_id",
  context: { isVip: true },
});

//Step 3: Fetch flags from the Flagship platform 
visitor.fetchFlags().then(()=>{
// Step 4: Retrieves a flag named "displayVipFeature"
  const flag = visitor.getFlag("displayVipFeature");
  
//Step 5: Returns the flag value ,or if the flag does not exist, it returns the default value "false"
  console.log("flag value", flag.getValue(false))
});

// Retrieving flags with an event listener
//...import code

// Step 1: start the SDK
Flagship.start("your_env_id", "your_api_key");

//Step 2: Create a visitor
const visitor = Flagship.newVisitor({
  visitorId: "your_visitor_id",
  context: { isVip: true },
});

visitor.on("ready",  (error) => {
  if (error) {
    //do some stuff
    return;
  }

// Step 4: Retrieves a flag named "displayVipFeature"
  const flag = visitor.getFlag("displayVipFeature");
  
//Step 5: Returns the flag value ,or if the flag does not exist, it returns the default value "false" */
	console.log("flag value", flag.getValue(false))
});

//Step 3: Fetch flags from the Flagship platform 
visitor.fetchFlags();

👍

Good to know

By default, the SDK assumes that the visitor has been exposed to the flag when flag.getValue() is called, so it sends the flag exposure hit to flagship server. However, this behavior can be changed. Click here for more details.

Tracking hits

Step 6: Send hits to Flagship using the sendHit method of the visitor instance. These hits help validate your objectives (KPIs) set up in your campaign.

import { HitType, EventCategory } from "@flagship.io/js-sdk";

// ... other code

visitor.sendHit({
  type: HitType.EVENT, 
  category: EventCategory.USER_ENGAGEMENT,
  action: "click",
  label: "label",
  value: 100,
});

Updated 6 months ago