Flutter V1.2.X


SDK overview

Welcome to the Flagship Flutter SDK documentation!

The following documentation helps you run Flagship on your Flutter app using our client library.

Feel free to contact us if you have any questions regarding this documentation.

SDK features

This SDK version will help you:


  • Flagship SDK supports Dart 2.12.0 minimum or higher
  • Flagship is null safety

Good to know

Getting Started

Our Flagship flutter SDK is available for distribution through pub.dev


Run this command:

flutter pub add flagship

This will add a line like this to your package's pubspec.yaml (and run an implicit dart pub get):

  flagship: ^1.2.0


To run experiments with Flagship, you will need to start the SDK using:

start(String envId, String apiKey, {FlagshipConfig? config})

envIdStringYesIdentifies your Flagship account and environment (preprod or prod). Find this ID
apiKeyStringYesIdentifies your Flagship api key (preprod or prod). Find this api key
configFlagshipConfigNoObject that represent client's configuration


You can get your own envId & API Key in the Flagship Platform.

  1. Navigate to SettingsAPI Key & Settings
  2. Copy the environment ID & API Key
// import package
import 'package:flagship/flagship.dart';
import 'package:flagship/utils/logger/log_manager.dart';

/////// Start sdk with default options ///////

Flagship.start("your_env_id", "your_api_key");

/////// Start sdk with custom options  ///////

// - timeout   = 1500 ms
// - level     = warning message
// - activated = true
// - statusListener callback 
    Flagship.start("your_env_id", "your_api_key",
        config: FlagshipConfig(
            timeout: 1500,
            logLevel: Level.WARNING,
            activeLog: true,
            statusListener: (newStatus) {
              // This callback is triggered when the SDK status has changed

Flagship configuration options

The sdk provides the FlagshipConfig object in the start function as an optional parameter where we can set the desired configuration

FlagshipConfig(this.timeout,{Level logLevel = Level.ALL, bool activeLog = true})

timeoutintNo Timeout to fetch campaigns. The default value is 2000 ms (Milliseconds).
statusListenervoid Function(Status newStatus)No Called when the sdk status changed
logLevelLevelNo Log's level of detail : NONE(0), EXCEPTIONS(1), ERROR(2), WARNING(3), DEBUG(4), INFO(5), ALL(6) which is the default value
activeLogboolNo By default the value is true (activated logs)


This delay only concerns the request for fetching campaigns under the API mode. If the API didn't answer during this interval of time, the default values will be returned from the getModification function.


The Timeout default value is 2000 Milliseconds


This listener is called when SDK status has changed.

//-- Code Sample: Status listener --// 

// Create a configuration object with status listener
   FlagshipConfig config = FlagshipConfig(statusListener: (Status newStatus) {
      switch (newStatus) {
        case Status.READY:
          // Create or use a visitor

logLevel :
You can change log's level of detail durring the runtime void setLoggerLevel(Level newLevel)

// Change the log's level of detail


The default value for the level of detail is Level.ALL

activeLog :
You can enable or disable the logger durring the runtime void enableLog(bool isLogEnabled)

// Disable logs


The default value for activeLog is true

Display logs

void logger(Level level, String message, {bool isJsonString = false})

levelLevelYesLevel of details regarding messages
messageStringYesMessage to display
isJsonStringboolNoFalse by default, use true when it's about json representation to get a pretty print
/////// Logger function to display message ///////

Flagship.logger(Level.ALL, "start sdk");

SDK Status

It is possible to get the current status via the method getStatus() from the Flagship class.

  • static Status getStatus()

Return an enum that represent the current SDK status

List of the possible SDK status :

NOT_INITIALIZED Flagship SDK has not been started or initialized successfully.
PANIC_ON Flagship SDK is ready but is running in Panic mode: All visitor's features are disabled except 'synchronizeModifications' which refreshes this status.
READY Flagship SDK is ready to use.
// Get the current status for the SDK
   var currentStatus = Flagship.getStatus();

// Using getStatus to check if the SDK is READY

  // Create the visitor 
   var visitor = Flagship.newVisitor("user1",{"isVip":true});

  // Synchronize the modifications 
   visitor.synchronizeModifications().whenComplete(() {
  // Get the status and check the mode
    Status currentState =  Flagship.getStatus();
    if (currentState == Status.READY) {
      // The SDK is ready

Create a visitor

Once Flagship SDK is initialized, you can create a visitor.

newVisitor(String visitorId,Map<String, Object> context,{bool hasConsented = true})

visitorIdStringYesUnique identifier for the current visitor. This can be an ID from your database or a session ID. If no value is passed, the SDK will automatically generate a unique ID. Learn more
contextMap<String, Object>YesContext that represent the visitor's attributs. ex {"isVip":true}
hasConsentedboolNoSpecify if the visitor has consented for personal data usage. true by default.

The visitor context is a property dataset that defines the current visitor of your app.
This dataset is sent and used by the Flagship Decision API as targeting criteria for campaign assignment.

For example, if you want to enable or disable a specific feature based on VIP status, you would pass this attribute as a key-value pair in the visitor context so that the Decision API can enable or disable the corresponding feature flag for the visitor.

// import package
import 'package:flagship/flagship.dart';

/////// Create visitor with no consent ///////
var visitor = Flagship.newVisitor("your_visitorId", {"isVip": true}, hasConsented: false);


  • Context keys must have a type of String
    • Context values must have a type of String, bool, int,double
    • User context keys and values are case sensitive

Get & Set the current visitor

Most of the time, your Flutter application will handle only 1 visitor at any given time.
For that use case, Flagship implement 2 useful methods to store the created visitor as the current singleton visitor instance.

static setCurrentVisitor(Visitor visitor)

Stores the current visitor instance created at the newVisitor.

// import package
import 'package:flagship/flagship.dart';

/////// set the current visitor //////////
var visitor = Flagship.newVisitor("your_visitorId", {"isVip": true});

static Visitor? getCurrentVisitor()

Return the current visitor instance stored when setting the current visitor.

// import package
import 'package:flagship/flagship.dart';

/////// Get the current visitor //////////

var visitor = Flagship.getCurrentVisitor();


This method returns a nullable Visitor (in case the current visitor has not been previously set).
Make sure to check whether it is null or not before using it.

Updating the visitor context

The visitor context is a property dataset that defines the current visitor of your app. This dataset is sent and used by the Flagship Decision API as targeting criteria for campaign assignment.

The following method from the Visitor instance allows you to set new context values matching the given keys.

void updateContext(String key, Object value)

Update the visitor context values, matching the given keys, used for targeting. Only String, bool, int, double typed values are accepted.

keyStringContext key.
valueObjectContext value.

void updateContextWithMap(Map<String, Object> context)

Update the visitor context values, matching the given keys, used for targeting. Only String, bool, double and int type values are accepted.

contextMap<String, Object>Map of keys, values.


  • User context keys must have a type of String
    • User context values must have a type of String, bool, double or int
    • User context keys and values are case sensitive
// import package
import 'package:flagship/flagship.dart';

/////// Update context ///////

var currentVisitor = Flagship.getCurrentVisitor();

// Update context with key/value
currentVisitor?.updateContext("lastPurchaseDate", 1615384464);

// Update context with Map
currentVisitor?.updateContextWithMap({"isVip": true, "key1": 12.5, "key2": "title", "key3": 2});

void clearContext()

Empty the visitor context values, used for targeting.

// Import package
import 'package:flagship/flagship.dart';

/////// Clear context ///////

var currentVisitor = Flagship.getCurrentVisitor();


Managing visitor campaigns

Synchronizing campaigns

The synchronizeModifications() method of the visitor instance automatically calls the Flagship Decision API to run campaign assignments according to the current visitor context and retrieve applicable modifications.

These modifications are then stored in the SDK and updated asynchronously when synchronizeModifications() is called.

/////// Synchronize modifications ///////

// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();

// Synchronize
currentVisitor?.synchronizeModifications().whenComplete(() {
  // The Synchronize is done.
  // If the panic mode is ON or the synchronize fail for another reason
  // the getModification will return the default value

Future<void> synchronizeModifications() async

This function will call the decision api and update all the campaigns modifications from the server according to the visitor context.

Getting modifications

Once the campaign has been assigned and synchronized, all the modifications are stored in the SDK.
You can retrieve these modifications using the following functions from the Visitor instance:

/////// Get modification ///////

// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();

// Synchronize
currentVisitor?.synchronizeModifications().whenComplete(() {
  // Get modification for "btnTitle"
  var titleBtn = currentVisitor.getModification("btnTitle", "default value");

// The getModification function can be directly called through the "currentVisitor" instance if you 
// already synchronized it elsewhere in the application

dynamic getModification(String key, Object defaultValue,{bool activate = false})

Retrieve a modification value by its key. If no modification match the given key or if the stored value type and default value type do not match, default value will be returned.

keyStringYesKey associated to the modification.
defaultValueObjectYesDefault value to return.
activatebooleanNoSet this parameter to true to automatically report on our server that the current visitor has seen this modification. It's possible to call activateModification() later.

Activating modifications

Once a modification is displayed on the screen for a user (and if your activate parameter was false in the getModification method), you must send an activate event to tell Flagship that the user has seen this specific variation.

Future<void> activateModification(String key) async

keyStringYesKey associated with the modification.
/////// Activate modification ///////

var currentVisitor = Flagship.getCurrentVisitor();

//Activate modification for "btnTitle"
await currentVisitor?.activateModification("btnTitle");

Getting modification information

You may need to send the campaign's information to a third-party for reporting and/or analytics purposes. The getModificationInfo method returns a Map with values you can use.

These values are:

campaignIdStringid for the campaign
variationGroupIdStringId for the variation group
variationIdStringid for variation selected
isReferenceBoolIf true that means the selected variation is a reference, otherwise not a reference.

Map<String, Object> getModificationInfos(String key)

keyStringYesKey associated with the modification.
/////// Retreive modification info ///////

var currentVisitor = Flagship.getCurrentVisitor();

// Retreive modification information for "btnTitle"
var inofs = currentVisitor?.getModificationInfo("btnTitle");


  • Return Map<String, Object> with keys : campaignId, variationGroupId , variationId and isReference (e.g. { “campaignId”: “xxxx”, “variationGroupId”: “xxxx“, “variationId”: “xxxx”, "isReference":true})
  • Return null if key modification doesn't exist

Managing visitor consent

The Visitor class provides a method to let you manage visitor consent for data privacy usage. When false the activation and hits will be disabled.

/////// Manage visitor consent ///////

// Create visitor with no consent
var visitor = Flagship.newVisitor(visitorIdController.text, visitorContext, hasConsented:false);
// Set the consent to true on run time

Hit Tracking

This section helps send tracking and learn how to build hits in order to track campaign goals.

The different types of Hits are:

They must all be built and sent with the following method of the visitor instance:

Future<void> SendHit(hit HitProtocol)

Common parameters

These parameters can be sent with any type of hit.

userIpStringoptional User IP
screenResolutionStringoptional Screen Resolution.
userLanguageStringoptional User Language
sessionNumberintoptional Session Number

Hit types


This hit should be sent each time a visitor arrives on a new interface.

Hit parameterTypeRequiredDescription
locationStringYesName of the screen
/////// Screen hit ///////

var visitor = Flagship.getCurrentVisitor();
// Send screen hit 
visitor?.sendHit(Screen(location: "My page"));


This hit should be sent when a user complete a Transaction.

Hit ParameterTypeRequiredDescription
transactionIdStringYesTransaction unique identifier.
affiliationStringYesTransaction name. Name of the goal in the reporting.
revenuedouble?NoTotal revenue associated with the transaction. This value should include any shipping or tax costs.
shippingdouble?NoSpecifies the total shipping cost of the transaction.
shippingMethodString?NoSpecifies the shipping method of the transaction.
taxdouble?NoSpecifies the total taxes of the transaction.
currencyString?NoSpecifies the currency used for all transaction currency values. Value should be a valid ISO 4217 currency code.
paymentMethodString?NoSpecifies the payment method for the transaction.
itemCountint?NoSpecifies the number of items for the transaction.
couponCodeString?NoSpecifies the coupon code used by the customer for the transaction.
/////// Transaction hit ///////

var visitor = Flagship.getCurrentVisitor();
  transactionId   : "YOUR_TRANSACTION_ID",
  affiliation     : "GOAL_NAME", // The goal name set in Flagship campaign
  revenue         :	100,
  shipping        :	10,
  tax             :	5,
  currency        : "EUR",
  couponCode      : "discount",
  paymentMethod   : "Card",
  shippingMethod  : "postal",
  itemCount       : 2,


This hit is linked to a transaction. It must be sent after the corresponding transaction.

Hit ParameterTypeRequired Description
transactionIdStringYesTransaction unique identifier.
nameStringYesProduct name.
codeStringYesSpecifies the item code or SKU.
pricedouble?NoSpecifies the item price.
categoryString?NoSpecifies the item category.
quantityint?NoSpecifies the item quantity
/////// Item hit ///////

var visitor = Flagship.getCurrentVisitor();
  transactionId	: "YOUR_TRANSACTION_ID",
  name					: "item name",
  code					: "item code",
  price					: 10.5,
  quantity			: 5,
  category			: "item category"


This hit can be anything you want: for example a click or a newsletter subscription.

Hit ParameterTypeRequired Description
CategoryCategoryEventYesCategory of the event ("Action_Tracking" or "User_Engagement").
ActionStringYesThe event action. Should match the goal name of the campaign
LabelStringNoLabel of the event.
ValueintNoSpecifies a value for this event. must be non-negative.
/////// Event hit ///////

var visitor = Flagship.getCurrentVisitor();
  action		: "Event action", // The name of the goal defined in your campaign
  category	: CategoryEvent.Action_Tracking,
  label			: "custom label",
  value			: 2