Implementation

This quickstart guides you through initializing the Flagship SDK, Getting flags and sending Hit.

Import Flagship SDK

In order to use the SDK, you have to import the Flagship SDK bundle from this CDN

<script src="https://unpkg.com/@flagship.io/js-sdk/dist/index.browser.js"><script>

Initialization

The aim of this step is to give to the SDK all information necessaries which the Flagship SDK will use in order to fetch data from your Flagship account and define the SDK running behaviors

Flagship.start("yourEnvId", "yourApiKey");

You just need to call the static method start of Flagship class with parameters envId and apiKey from your Flagship account. Learn more

Create a visitor

Once the SDK is initialized, the next step is to create a visitor. With this visitor instance, you'll be able to get all your available flags defined in Flagship, send hit, etc.

const selectedZone = document.querySelector("#zone");

//when fetch property is unset or true, newVisitor will call synchronizeModifications automatically
const visitor = Flagship.newVisitor({
    hasConsented: true,
    context: {
        zone: selectedZone.value,
    },
});

This code will create a visitor with context the geographic zone where user is connected. We don't set visitorId property so, the SDK will generate one for us.
hasConsented is set to true so that to track some user action. learn more about consent

Here the geographic zone comes from a list on the UI but you can get this information either by IP or by a third-party service.

In this step, you define all information about the user, which will be used in the targeting process. learn more

Get my flags

In order to get your flags defined in Flagship, you have to fetch Flags. The fetchFlags method will request Flagship and get all flags according to user targeting

const loader = document.getElementById("loader");
const googleLogin = document.getElementById("google-btn");
const weChatLogin = document.getElementById("wechat-btn");

//listen visitor to be ready
visitor.on("ready", function (error) {
  if (error) {
    console.log("error", error);
  }

  // step 5 get flags
  const flagLoginWithGoogle = visitor.getFlag("login-with-google");
  const flagLoginWithWechat = visitor.getFlag("login-with-wechat");
  const flagLoginBtnColor = visitor.getFlag("login-btn-color");

  const loginOr = document.getElementById("login-or");

  //Hide or show google login according to flag login-with-google

  const isLoginWithGoogle = flagLoginWithGoogle.getValue(false); //by default calling the getValue method will automatically send an activation to the flagship
  if (isLoginWithGoogle) {
    googleLogin.classList.remove("d-none");
  } else {
    googleLogin.classList.add("d-none");
  }

  //Hide or show wechat login according to flag login-with-wechat
  const isLoginWithWechat = flagLoginWithWechat.getValue(false);
  if (isLoginWithWechat) {
    weChatLogin.classList.remove("d-none");
  } else {
    weChatLogin.classList.add("d-none");
  }

  if (!isLoginWithGoogle && !isLoginWithWechat) {
    loginOr.classList.add("d-none");
  } else {
    loginOr.classList.remove("d-none");
  }

  //Change login form button color according to the flag `login-btn-color`
  const loginBtnColor = flagLoginBtnColor.getValue("#0d6efd");
  const loginBtn = document.querySelector("form button");
  loginBtn.style.backgroundColor = loginBtnColor;
  loginBtn.style.borderColor = loginBtnColor;

  setTimeout(() => {
    loader.classList.add("d-none");
  }, 200);
});

visitor.fetchFlags() // fetch all Flags

Once the fetchFlags method process is done, the SDK will trigger the "Ready" event in the visitor instance to let know you that all your flags are ready to be used.

We call the getFlag method from the callback of the "Ready" event to get the 3 flags (login-with-google, login-with-wechat and login-btn-color ) defined in Flagship. Then, we activate each flag to report to Flagship that the current visitor has seen it.

Sometimes, the callback of the Ready event can have an error as a parameter if something wrong happened. Learn more

Send hits

The aim is to track some user actions in order to get reports about them

const loginForm = document.getElementById("login-form");

//send hit
loginForm.addEventListener("submit", (e) => {
    e.preventDefault();
    visitor.sendHit({
        type: "EVENT",
        category: "Action Tracking",
        action: "submit-basic-login",
    });
});

//send hit
googleLogin.addEventListener("click", () => {
    visitor.sendHit({
        type: "EVENT",
        category: "Action Tracking",
        action: "click-google-login",
    });
});

//send hit
weChatLogin.addEventListener("click", () => {
    visitor.sendHit({
        type: "EVENT",
        category: "Action Tracking",
        action: "click-wechat-login",
    });
});

In this code, if a visitor has logged in with the login form, an Event hit with the action "submit-basic-login" will be sent to Flagship with "click-google-login" if the login process used is google and with "click-wechat-login" if wechat is used. Learn more

The visitor has to consent otherwise the SDK won't send hits.

Github repos

See repos Github