Flutter V1.3.X
Introduction
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:
- Set a visitor ID
- Update visitor context
- Synchronize campaigns via the Decision API
- Get a flag value
- Send a hit to our Data Collect
Prequisites
- Flagship SDK supports Dart 2.12.0 minimum or higher
- Flagship is null safety
Good to know
- Latest Version
- Github repository
- Dart code supported
Getting Started
Our Flagship flutter SDK is available for distribution through pub.dev
Installing
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):
dependencies:
flagship: ^1.3.0
Initialization
To run experiments with Flagship, you will need to start the SDK using:
start(String envId, String apiKey, {FlagshipConfig? config})
Parameter | Type | Required | Description |
---|---|---|---|
envId | String | Yes | Identifies your Flagship account and environment (preprod or prod). Find this ID |
apiKey | String | Yes | Identifies your Flagship api key (preprod or prod). Find this api key |
config | FlagshipConfig | No | Object that represent client's configuration |
You can get your own envId & API Key in the Flagship Platform.
- Navigate to Settings⟶API Key & Settings
- 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})
Parameter | Type | Required | Description |
---|---|---|---|
timeout | int | No | Timeout to fetch campaigns. The default value is 2000 ms (Milliseconds). |
statusListener | void Function(Status newStatus) | No | Called when the sdk status changed |
logLevel | Level | No | Log's level of detail : NONE(0), EXCEPTIONS(1), ERROR(2), WARNING(3), DEBUG(4), INFO(5), ALL(6) which is the default value |
activeLog | bool | No | By default the value is true (activated logs) |
Timeout:
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
statusListener:
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
break;
default:
}
});
logLevel :
You can change log's level of detail durring the runtime void setLoggerLevel(Level newLevel)
// Change the log's level of detail
Flagship.setLoggerLevel(Level.INFO);
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
Flagship.enableLog(false);
The default value for activeLog is true
Display logs
void logger(Level level, String message, {bool isJsonString = false})
Parameter | Type | Required | Description |
---|---|---|---|
level | Level | Yes | Level of details regarding messages |
message | String | Yes | Message to display |
isJsonString | bool | No | False 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 :
Status | Description |
---|---|
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 'fetchFlags' 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});
// Fetch Flags the modifications
visitor.fetchFlags().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})
Parameter | Type | Required | Description |
---|---|---|---|
visitorId | String | Yes | Unique 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 |
context | Map<String, Object> | Yes | Context that represent the visitor's attributs. ex {"isVip":true} |
hasConsented | bool | No | Specify 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});
Flagship.setCurrentVisitor(visitor);
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.
Parameter | Type | Description |
---|---|---|
key | String | Context key. |
value | Object | Context 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.
Parameter | Type | Description |
---|---|---|
context | Map<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
orint
- 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();
currentVisitor?.clearContext();
Managing visitor campaigns and theirs flags
Fetching Flags
The fetchFlags()
method of the visitor
instance automatically calls the Flagship Decision API to run campaign assignments according to the current visitor context and retrieve applicable flags.
These flags are updated asynchronously when fetchFlags()
is called.
/////////////////////////////////////////
/////// Fetch Flags ///////
/////////////////////////////////////////
import 'package:flagship/flagship.dart';
// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();
// Fetch Flags
currentVisitor?.fetchFlags().whenComplete(() {
// The fetch is done.
// If the panic mode is ON or the fetch fail for another reason
// the value for flag will be a default value
});
Future<void> fetchFlags() async
This function will call the decision api and update all the campaigns flags from the server according to the visitor context.
Getting flags
Once the campaign has been assigned and fetched, all the flags are stored in the SDK.
You can retrieve these flags using the following functions from the Visitor
instance:
////////////////////////////////
/////// Get Flag ///////
////////////////////////////////
import 'package:flagship/flagship.dart';
import 'package:flagship/model/flag.dart';
// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();
// Fetch flags
currentVisitor?.fetchFlags().whenComplete(() {
// Ex: get flag for vip feature
Flag flag = currentVisitor.getFlag("displayVipFeature",false);
});
// The getFlag function can be directly called through the "currentVisitor" instance if you
// already fetched it elsewhere in the application
Flag getFlag<T>(String key, T defaultValue)
Retrieve a Flag object by its key. If no flag match the given key an empty flag will be returned. Call exists() to check if the flag has been found.
Parameter | Type | Required | Description |
---|---|---|---|
key | String | Yes | Key associated to the modification. |
defaultValue | T | Yes | Flag default value to return. |
Getting flags current values
To retrieve flag current value, simply call value() method of the Flag object.
T value({bool userExposed: true})
Returns the value from the assigned campaign variation or the Flag default value if the Flag does not exist, or if types are different.
Parameter | Type | Default value | Description |
---|---|---|---|
userExposed | bool | true | Tells Flagship the user have been exposed and have seen this flag. This will increment the visits for the current variation on your campaign reporting. If needed it is possible to set this param to false and call userExposed() afterward when the user has really been exposed to it. |
import 'package:flagship/flagship.dart';
import 'package:flagship/model/flag.dart';
// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();
// Fetch flags
currentVisitor?.fetchFlags().whenComplete(() {
// Ex: get flag for vip feature
Flag flag = currentVisitor.getFlag("displayVipFeature", false);
// Use this flag value to enable displaying the vip feature
bool shouldDisplayVipFeature = flag.value();
});
Getting flags campaigns metadata
You may need to send campaign's informations to a third-party for reporting and/or analytics purposes. The metadata
method returns a dictionary with values you can use.
FlagMetadata metadata()
Return the campaign metadata or an empty object if the Flag doesn't exist or if the default value type does not correspond to the Flag type in Flagship.
import 'package:flagship/flagship.dart';
import 'package:flagship/model/flag.dart';
// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();
// Fetch flags
currentVisitor?.fetchFlags().whenComplete(() {
// Ex: get flag for vip feature
Flag flag = currentVisitor.getFlag("displayVipFeature", false);
// Use this flag value to enable displaying the vip feature
bool shouldDisplayVipFeature = flag.value();
// Use this flag to get the metadata
FlagMetadata metadata = flag.metadata();
});
The metadata
you can access to are the following one:
FSFlagMetadata | Type | Default value | Description |
---|---|---|---|
campaignId | String | "" | id of the campaign |
variationGroupId | String | "" | Id of the variation group |
variationId | String | "" | id of the variation assigned |
isReference | bool | false | if true that means the assigned variation is the reference, otherwise it's not. |
campaignType | String | "" | Type of the campaign. Ex: AB |
slug | String | "" | campaign slug or empty string if not configured in the platform |
Report a Flag exposition
By default when the method value()
is called, the SDK considers that the user has seen your Flag unless you pass false
to value()
. In this last case, you will have to call the userExposed()
method.
There are two options for exposing a user to a flag:
- Pass an userExposed=true parameter to the value() method.
- Use the following userExposed() method from the Flag instance.
Future<void> userExposed() async
// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();
// Fetch flags
currentVisitor?.fetchFlags().whenComplete(() {
// Ex: get flag for vip feature
Flag flag = currentVisitor.getFlag("displayVipFeature", false);
// Use this flag value to enable displaying the vip feature with expose to false
bool shouldDisplayVipFeature = flag.value(userExposed: false);
// Expose this flag later in the code
flag.userExposed();
});
Check if a Flag exists
bool exists()
This method will returntrue
if a Flag has been returned by Flagship.
// Get the current visitor
var currentVisitor = Flagship.getCurrentVisitor();
// Fetch flags
currentVisitor?.fetchFlags().whenComplete(() {
// Ex: get flag for vip feature and check if it exists
bool isDisplayVipFeatureExists = currentVisitor.getFlag("do_not_exists", false).exists();
});
}
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
visitor.setConsent(true);
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.
Parameter | Type | Description |
---|---|---|
userIp | String | optional User IP |
screenResolution | String | optional Screen Resolution. |
userLanguage | String | optional User Language |
sessionNumber | int | optional Session Number |
Hit types
Screen
This hit should be sent each time a visitor arrives on a new interface.
Hit parameter | Type | Required | Description |
---|---|---|---|
location | String | Yes | Name of the screen |
//////////////////////////
/////// Screen hit ///////
//////////////////////////
var visitor = Flagship.getCurrentVisitor();
// Send screen hit
visitor?.sendHit(Screen(location: "My page"));
Transaction
This hit should be sent when a user complete a Transaction.
Hit Parameter | Type | Required | Description |
---|---|---|---|
transactionId | String | Yes | Transaction unique identifier. |
affiliation | String | Yes | Transaction name. Name of the goal in the reporting. |
revenue | double? | No | Total revenue associated with the transaction. This value should include any shipping or tax costs. |
shipping | double? | No | Specifies the total shipping cost of the transaction. |
shippingMethod | String? | No | Specifies the shipping method of the transaction. |
tax | double? | No | Specifies the total taxes of the transaction. |
currency | String? | No | Specifies the currency used for all transaction currency values. Value should be a valid ISO 4217 currency code. |
paymentMethod | String? | No | Specifies the payment method for the transaction. |
itemCount | int? | No | Specifies the number of items for the transaction. |
couponCode | String? | No | Specifies the coupon code used by the customer for the transaction. |
///////////////////////////////
/////// Transaction hit ///////
///////////////////////////////
var visitor = Flagship.getCurrentVisitor();
visitor?.sendHit(Transaction(
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,
));
Item
This hit is linked to a transaction. It must be sent after the corresponding transaction.
Hit Parameter | Type | Required | Description |
---|---|---|---|
transactionId | String | Yes | Transaction unique identifier. |
name | String | Yes | Product name. |
code | String | Yes | Specifies the item code or SKU. |
price | double? | No | Specifies the item price. |
category | String? | No | Specifies the item category. |
quantity | int? | No | Specifies the item quantity |
////////////////////////
/////// Item hit ///////
////////////////////////
var visitor = Flagship.getCurrentVisitor();
visitor?.sendHit(Item(
transactionId : "YOUR_TRANSACTION_ID",
name : "item name",
code : "item code",
price : 10.5,
quantity : 5,
category : "item category"
));
Event
This hit can be anything you want: for example a click or a newsletter subscription.
Hit Parameter | Type | Required | Description |
---|---|---|---|
Category | CategoryEvent | Yes | Category of the event ("Action_Tracking" or "User_Engagement"). |
Action | String | Yes | The event action. Should match the goal name of the campaign |
Label | String | No | Label of the event. |
Value | int | No | Specifies a value for this event. must be non-negative. |
/////////////////////////
/////// Event hit ///////
/////////////////////////
var visitor = Flagship.getCurrentVisitor();
visitor?.sendHit(Event(
action : "Event action", // The name of the goal defined in your campaign
category : CategoryEvent.Action_Tracking,
label : "custom label",
value : 2
));
Updated about 2 months ago