Retrieving Flags

Within the Flagship SDK, a flag is an object that controls a feature behavior in your application. Flags can be used to enable or disable features, control rollouts of new features, or to customize the user experience. They are managed remotely through the Flagship platform in decision api mode and locally in bucketing mode , allowing you to modify your application's behavior in real-time without needing to deploy new code.

Getting a single flag

The getFlag method of the visitor instance allows you 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. For additional details, refer to your specific SDK reference documentation.

Before getting your first flags, you need to fetch them from the Flagship platform by calling the fetchFlags method.

Below are examples in different programming environments:

//...start the SDK code

const visitor = Flagship.newVisitor({
  visitorId: "your_visitor_id",
  context: { isVip: true },
});

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

// Retrieves a flag named "yourFlagKey"
const flag = visitor.getFlag("yourFlagKey");

//get the flag value, and if the flag is not found, returns the default value
console.log("flag value", flag.getValue("defaultValue"))

import React from "react";
import { FlagshipProvider, useFsFlag } from "@flagship.io/react-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="<ENV_ID>"
      apiKey="<API_KEY>"
      visitorData={{
        id: "<VISITOR_ID>",
        hasConsented: true, 
          context: {
            isVIP: true,
          }
      }}
    >
      <Component/>
    </FlagshipProvider>
  </>
);

const Component = () => {
  // Retrieves a flag named "yourFlagKey"
  const yourFlag = useFsFlag("yourFlagKey");
  // Get the flag value, and if the flag is not found, returns the default value
  const flagValue = yourFlag.getValue("defaultValue");

  return (
    <div>
      <h1>My component</h1>
      <p>Flag value: {flagValue}</p>
    </div>
  );
};

import React from "react";
import { FlagshipProvider, useFsFlag } from "@flagship.io/react-native-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="<ENV_ID>"
      apiKey="<API_KEY>"
      visitorData={{
        id: "<VISITOR_ID>",
        hasConsented: true, 
          context: {
            isVIP: true,
          }
      }}
    >
      <Component/>
    </FlagshipProvider>
  </>
);

const Component = () => {
  // Retrieves a flag named "yourFlagKey"
  const yourFlag = useFsFlag("yourFlagKey");
  // Get the flag value, and if the flag is not found, returns the default value
  const flagValue = yourFlag.getValue("defaultValue");

  return (
    <div>
      <h1>My component</h1>
      <p>Flag value: {flagValue}</p>
    </div>
  );
};

use Flagship\Flagship;

//...start the SDK code


$visitor = Flagship::newVisitor("<VISITOR_ID>", true)
        ->setContext(["isVip" => true])
        ->build();

// Fetch flag from the Flagship platform 
$visitor->fetchFlags();

// Retrieves a flag named "yourFlagKey"
$flag = $visitor->getFlag("yourFlagKey");

//get the flag value, and if the flag is not found, returns the default value
echo "Flag value: ".$flag->getValue("defaultValue");

//Batch all the collected hits and send them
Flagship::close();

using Flagship.Main;

//...start the SDK code

var visitor = Fs.NewVisitor("<VISITOR_ID>", true)
  .SetContext(new Dictionary<string, object> {
    { "isVip", true }
  })
  .Build();

// Fetch flag from the Flagship platform 
await visitor.FetchFlags();

// Retrieves a flag named "yourFlagKey"
var flag = visitor.GetFlag("yourFlagKey");

//get the flag value, and if the flag is not found, returns the default value
Console.WriteLine(flag.GetValue("defaultValue"));

Getting a collection of flags

The visitor instance also provides the getFlags that allows you to retrieve all of the visitor's flags as collection.From this collection, you can retrieve a specific flag, iterate over them, expose all flags, and more. For additional details, refer to your specific SDK reference documentation.

Below are examples in different programming environments:

//...start the SDK code

const visitor = Flagship.newVisitor({
  visitorId: "your_visitor_id",
  context: { isVip: true },
});

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

// Retrieves all visitor's flags
const flagsCollection = visitor.getFlags();

const json = flagsCollection.toJSON();

import React from "react";
import { FlagshipProvider, useFlagship } from "@flagship.io/react-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="<ENV_ID>"
      apiKey="<API_KEY>"
      visitorData={{
        id: "<VISITOR_ID>",
        hasConsented: true, 
          context: {
            isVIP: true,
          }
      }}
    >
      <Component/>
    </FlagshipProvider>
  </>
);

const Component = () => {
  const { getFlags } = useFlagship();
  
  useEffect(() => {
    // Retrieves all visitor's flags
    const flagsCollection = getFlags();
    const json = flagsCollection.toJSON();
  }, []);

  return (
    <div>
      <h1>My component</h1>
    </div>
  );
};

import React from "react";
import { FlagshipProvider, useFlagship } from "@flagship.io/react-native-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="<ENV_ID>"
      apiKey="<API_KEY>"
      visitorData={{
        id: "<VISITOR_ID>",
        hasConsented: true, 
          context: {
            isVIP: true,
          }
      }}
    >
      <Component/>
    </FlagshipProvider>
  </>
);

const Component = () => {
  const { getFlags } = useFlagship();
  
  useEffect(() => {
    // Retrieves all visitor's flags
    const flagsCollection = getFlags();
    const json = flagsCollection.toJSON();
  }, []);

  return (
    <div>
      <h1>My component</h1>
    </div>
  );
};

use Flagship\Flagship;

//...start the SDK code


$visitor = Flagship::newVisitor("<VISITOR_ID>", true)
        ->setContext(["isVip" => true])
        ->build();

// Fetch flag from the Flagship platform 
$visitor->fetchFlags();

// Retrieves all visitor's flags
$flagsCollection = $visitor->getFlags();

$json = $flagsCollection->toJSON();

//Batch all the collected hits and send them
Flagship::close();

using Flagship.Main;

//...start the SDK code

var visitor = Fs.NewVisitor("<VISITOR_ID>", true)
  .SetContext(new Dictionary<string, object> {
    { "isVip", true }
  })
  .Build();

// Fetch flag from the Flagship platform 
await visitor.FetchFlags();

// Retrieves all visitor's flags
var flagsCollection = visitor.GetFlags();

var json = flagsCollection.ToJson();

Exposing flags

Exposing a flag notifies Flagship that the visitor has been exposed to and has seen this flag. Flagship uses this notification to increment the visit count for the current variation in your campaign reporting. A flag exposure is counted only once, even if a flag is exposed multiple times for the same visitorId.

Flags can be exposed using the getValue method of the Flag instance, the visitorExpose method of the Flag instance, or the exposeAll method of the Flag collection instance. Each exposure makes an HTTPS request to Flagship. For additional details, refer to your specific SDK reference documentation.

Below are examples in different programming environments:

//...start the SDK code

const visitor = Flagship.newVisitor({
  visitorId: "your_visitor_id",
  context: { isVip: true },
});

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

// Retrieves a flag named "yourFlagKey"
const flag = visitor.getFlag("yourFlagKey");

// Get the flag value and expose it to Flagship
console.log("flag value", flag.getValue("defaultValue"))

// Directly expose the flag to Flagship without reading the value
flag.visitorExpose()

// Retrieves all visitor's flags
const flagsCollection = visitor.getFlags();

// Expose all of the flags in the collection
flagsCollection.exposeAll();

import React from "react";
import { FlagshipProvider, useFlagship } from "@flagship.io/react-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="<ENV_ID>"
      apiKey="<API_KEY>"
      visitorData={{
        id: "<VISITOR_ID>",
        hasConsented: true, 
          context: {
            isVIP: true,
          }
      }}
    >
      <Component/>
    </FlagshipProvider>
  </>
);

const Component = () => {
  const { getFlags } = useFlagship();
  
  // Retrieves a flag named "yourFlagKey"
  const yourFlag = useFsFlag("yourFlagKey");
  
  // Get the flag value and expose it to Flagship
  const flagValue = yourFlag.getValue("defaultValue");
  
  // Directly expose the flag to Flagship without reading the value
	yourFlag.visitorExpose()

  useEffect(() => {
    // Retrieves all visitor's flags
    const flagsCollection = getFlags();
    // Expose all of the flags in the collection
    flagsCollection.exposeAll();
  }, []);

  return (
    <div>
      <h1>My component</h1>
    </div>
  );
};

import React from "react";
import { FlagshipProvider, useFlagship } from "@flagship.io/react-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="<ENV_ID>"
      apiKey="<API_KEY>"
      visitorData={{
        id: "<VISITOR_ID>",
        hasConsented: true, 
          context: {
            isVIP: true,
          }
      }}
    >
      <Component/>
    </FlagshipProvider>
  </>
);

const Component = () => {
  const { getFlags } = useFlagship();
  
  // Retrieves a flag named "yourFlagKey"
  const yourFlag = useFsFlag("yourFlagKey");
  
  // Get the flag value and expose it to Flagship
  const flagValue = yourFlag.getValue("defaultValue");
  
  // Directly expose the flag to Flagship without reading the value
	yourFlag.visitorExpose()

  useEffect(() => {
    // Retrieves all visitor's flags
    const flagsCollection = getFlags();
    // Expose all of the flags in the collection
    flagsCollection.exposeAll();
  }, []);

  return (
    <div>
      <h1>My component</h1>
    </div>
  );
};

use Flagship\Flagship;

//...start the SDK code


$visitor = Flagship::newVisitor("<VISITOR_ID>", true)
        ->setContext(["isVip" => true])
        ->build();

// Fetch flag from the Flagship platform 
$visitor->fetchFlags();

// Retrieves a flag named "yourFlagKey"
$flag = $visitor->getFlag("yourFlagKey");

// Get the flag value and expose it to Flagship
echo "Flag value: ".$flag->getValue("defaultValue");

// Directly expose the flag to Flagship without reading the value
$flag->visitorExpose()

// Retrieves all visitor's flags
$flagsCollection = $visitor->getFlags();

// Expose all of the flags in the collection
$flagsCollection->exposeAll();

//Batch all the collected hits and send them
Flagship::close();

using Flagship.Main;

//...start the SDK code

var visitor = Fs.NewVisitor("<VISITOR_ID>", true)
  .SetContext(new Dictionary<string, object> {
    { "isVip", true }
  })
  .Build();

// Fetch flag from the Flagship platform 
await visitor.FetchFlags();

// Retrieves a flag named "yourFlagKey"
var flag = visitor.GetFlag("yourFlagKey");

// Get the flag value and expose it to Flagship
Console.WriteLine(flag.GetValue("defaultValue"));

// Directly expose the flag to Flagship without reading the value
flag.VisitorExpose()

// Retrieves all visitor's flags
var flagsCollection = visitor.GetFlags();

// Expose all of the flags in the collection
flagsCollection.ExposeAll();

Please consult the reference documentation for your specific SDK for more detailed information:

SDK
Javascript
React-JS
React-Native
PHP
.NET