iOS V2.0.X
Introduction
SDK overview
Welcome to the Flagship iOS SDK documentation!
The following documentation helps you to run Flagship on your native iOS app using our client library with preconfigured methods to implement the Decision API.
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 user context
- Assign campaigns via the Decision API or Bucketing
- Get modifications
- Activate campaigns
- Send hits to our Universal Collect
Prequisites
- Your app must be a native app written in Swift or Objective C.
- Flagship SDK supports at least iOS 8.0+
- Swift Client application must use Swift 5 or higher
Good to know
- Github repository
- Swift and Objective-C code supported
- Weight: ~ 0.480 KB
Getting Started
Our Flagship iOS SDK is available for distribution through CocoaPods, Swift Package Manager or manual installation.
Cocoapods
-
Open Terminal and browse to the directory that contains your project then, enter the following command:
pod init
-
Open your Podfile and add the following line to the Podfile
target 'Your App' do
use_frameworks!
pod 'FlagShip'
end
-
Run
pod install
from your Xcode project's base directory -
Make sure you always open the Xcode workspace and not the project file when building your project
Manual Installation
-
In Finder, browse to the Flagship.framework file and move it under your "Embedded Binaries" section in Xcode
-
Upon moving it, a popup is displayed: check "Copy items if needed".
Apple Store Submission
Flagship FrameWork is universal and BitCode supported
The universal framework for iOS contains architectures for simulators and devices. You will therefore be able to run your application on all devices and all iOS simulators.
If your app contains a universal framework, the App Store will reject your app because of an unwanted architecture.
You need to add a new build phase, then select Run Script
to add a new build step after Embed frameworks
.
In the Shell
field, enter the script described below.
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
EXTRACTED_ARCHS=()
for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done
Swift Package Manager (SPM)
You can search for Flagship package on GitHub. Add your GitHub or GitHub Enterprise account in Xcode’s preferences, and a package repository appears as you type.
For more information about Swift Package Manager, refer to Apple documentation.
Initialization
To run experiments with Flagship, you will need to start the SDK. Flagship uses a sharedInstance
that can activate experiments and track events.
func start( envId:String, apiKey:String, visitorId:String?, config:FSConfig = FSConfig(), onStartDone:@escaping(FlagshipResult)
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 |
visitorId | String | Yes | Unique identifier for the current user. 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 |
config | FSConfig | No | Object that represent configuration client. Default values are (DECISION_API for the mode and 2 seconds for the api timeout) |
onStartDone | block | Yes | Indicates the codeblock to be invoked when the SDK is ready |
Notice Information
Unique identifier for the current user. 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
The SDK gives you the ability to change the
envId
for QA purposes. Don't forget to delete your app cache when changing environments.
FlagshipResult
indicates the state of the SDK, Ready or NotReady
- Ready: This status means the SDK is ready to use and you can get all modifications and send events
- NotReady: This status means that an error occured at the initialization (see the logs for reason) and only a default value is returned when you call
getModification
As the SDK is asynchronous and runs in parallel, this method enables you to set a block which will be executed when the SDK is ready.
Remember to replace "your EnvId" with your own.
- Navigate to Parameters⟶Environment & Security
- Copy the environment ID
import Flagship
////////////////////////////////////////////////////////////////////
/////////// Start SDK Flagship with default mode ///////////////////
////////////////////////////////////////////////////////////////////
/// By default the sdk will run under Decision api
/// Start the SDK
Flagship.sharedInstance.start(envId:"your envId", apiKey: "your apiKey", visitorId: "visitorId"){ (result) in
if result == .Ready {
DispatchQueue.main.async {
/// Update UI
}
}else{
/// An error occurs or the SDK is disabled
}
}
////////////////////////////////////////////////////////////////////
/////////// Start SDK Flagship with configuration //////////////////
////////////////////////////////////////////////////////////////////
/// init config object
let fsConfig = FSConfig(.BUCKETING) /// config with bucketing mode
---- or ---
/// init config object
let fsConfig = FSConfig(.DECISION_API, timeout: 0.2) /// config with Decision api mode and 0.2 second for timeout
/// Start the SDK
Flagship.sharedInstance.start(envId:"your envId", apiKey: "your apiKey", visitorId: "visitorId", config:fsConfig){ (result) in
if result == .Ready {
DispatchQueue.main.async {
/// Update UI
}
}else{
/// An error occurs or the SDK is disabled
}
}
////////////////////////////////////////////////////////////////////
/////////// To let Flagship generate a visitorId for you ///////////
////////////////////////////////////////////////////////////////////
/// Start Flagship with generated visitorId
Flagship.sharedInstance.start(envId:"your envId", apiKey: "your apiKey", visitorId:nil){ (result) in
if result == .Ready {
DispatchQueue.main.async {
/// Update UI
}
}else{
/// An error occurs or the SDK is disabled
}
}
// To get your generated visitorId, use:
Flagship.sharedInstance.visitorId
```
</TabItem>
<TabItem value="objectivec">
```Objective-C
/// init config object and set the running mode and timeout
FSConfig * config = [[FSConfig alloc] init:FlagshipModeDECISION_API timeout:0.2];
/// Start the sdk
[[Flagship sharedInstance] startWithEnvId:@"you envId" apiKey:@"your apiKey" visitorId:@"visitorId" config:config onStartDone:^(enum FlagshipResult result) {
if (result == FlagshipResultReady){
dispatch_async(dispatch_get_main_queue(), ^{
/// update UI
});
}else{
/// An error occurs or the SDK is disabled
}
}];
SDK Start Example
This example will walk you through the steps needed to configure a welcome message for VIP users:
This message will only be delivered to users with a VIP attribute present in the user context.
To get this message, update the user context with this attribute via the SDK:
/// Set the attribute isVip to true
Flagship.sharedInstance.updateContext("isVip", true)
```
Then you call the `start` function:
```swift
/// init config object
let fsConfig = FSConfig(.DECISION_API, timeout: 0.2) /// config with Decision api mode and 0.2 second for timeout
/// Start the SDK
Flagship.sharedInstance.start(envId:"your envId", apiKey: "your apiKey", visitorId: "visitorId", config:fsConfig){ (result) in
if result == .Ready {
DispatchQueue.main.async {
/// Update UI
}
}else{
/// An error occurs or the SDK is disabled
}
Once the state is Ready, you can access your modifications value from anywhere in your project.
Flagship configuration options
The sdk provide FSConfig object in start function as optional parameter where we can set the desired configuration
init(_ mode:FlagshipMode = .DECISION_API , timeout:TimeInterval = FS_TimeOutRequestApi)
Parameter | Type | Required | Description |
---|---|---|---|
mode | FlagshipMode | No | api or bucketing. The default value is DECISION_API |
timeout | TimeInterval | No | timeout to fetch campaigns . The default value is 2 seconds |
Flagship Mode:
-
When the SDK is running in
DECISION_API
mode, the campaign assignments and targeting validation take place server-side. In this mode, each call to thesynchronizeModifications
method to refresh the modifications will create an HTTP request. -
When the SDK is running in
BUCKETING
mode, the SDK downloads all the campaigns configurations at once in a single bucketing file so that variation assignment can be computed client-side by the SDK. This bucketing file is stored in cache and will only be downloaded again when campaign configurations are modified in the Flagship interface. Learn more
Notice Information
The default value is DECISION API.
Timeout:
This delay only concerns the request on fetching campaigns under the api mode. If the API didn't answer during this interval of time, the SDK will not wait longer for it and will use the modifications values already present on device's cache.
If there is no cache yet, the default values will be returned from the getModification function.
Notice Information
The Timeout default value is 2 seconds.
Updating the user context
The user context is a property dataset that defines the current user of your app. This dataset is sent and used by the Flagship Decision API as targeting criteria for campaign assignment.
For example, if you wanted to enable or disable a specific feature based on VIP status, you would pass that attribute as a key-value pair in the user context so that the Decision API can enable or disable the corresponding feature flag for the user.
Flagship.sharedInstance.updateContext("isVip", true)
User context values are used for targeting configuration.
The SDK provides a set of methods to push new user context values to Flagship.
These functions update the user context value matching the given key. If there isn't an existing value matching that key, a new context value associated with this key will be created.
-
Add Boolean Value to the user context:
func updateContext(_ key:String, _ boolean:Bool)
-
Add a Double Value to the user context:
func updateContext(_ key:String, _ double:Double)
-
Add a String Value to the user context:
func updateContext(_ key:String, _ text:String)
-
Add a Float Value to the user context:
func updateContext(_ key:String, _ float:Float)
-
Add a Integer Value to the user context:
public func updateContext(_ key:String, _ integer:Int)
Parameter | Type | Required | Description |
---|---|---|---|
key | String | Yes | Attribute key associated with the following value |
value | String, Double, Boolean, FLoat | Yes | Attribute value to add in the context |
- Add Dictionary to the user context:
func updateContext(_ contextValues:Dictionary<String,Any>)
Parameter | Type | Required | Description |
---|---|---|---|
contextValues | dictionary | Yes | Dictionary of key-value pairs (string, int, double, float, boolean) |
// - isVip with true value
// - basketNumber with value 10 in the user context
// - name with value "alice" in the user context
// - valueKey with value 1.2 in the user context
[[Flagship sharedInstance] updateContext:@{@"basketNumber":@10, @"isVip":@YES, @"name":@"alice", @"valueKey":@1.2}];
// Add basketNumber with value 10 in the user context
Flagship.sharedInstance.updateContext("basketNumber", 10)
// Add isVip with true value to the user context
Flagship.sharedInstance.updateContext("isVip", true)
// Add name with value "alice" to the user context
Flagship.sharedInstance.updateContext("name", "alice")
// Add valueKey with value 1.2 to the user context
Flagship.sharedInstance.updateContext("valueKey", 1.2)
// ---- Update context with dictionary ---
// Create dictionary
let dictionaryCtx:[String:Any] = ["basketNumber": 10,"isVip":true,"name":"alice","valueKey": 1.2]
// Update context
Flagship.sharedInstance.updateContext(dictionaryCtx)
Predefined user context keys
The Flagship SDK contains predefined user context keys that do not count against your plan quota. Some of the predefined keys will automatically set their values, but you can always override them if needed. These key-value pairs are sent to Flagship and be available in the "Persona" section of the Flagship interface.
func updateContext(configuredKey:PresetContext, value:Any)
Parameter | Type | Required | Description |
---|---|---|---|
configuredKey | PresetContext | Yes | The values defined in an enumeration PresetContext |
value | String, Double, Boolean, FLoat | Yes | the value to add in the context |
For a full list of the predefined keys, see the appendix.
/// Update context
[[Flagship sharedInstance] updateContext:@{@"basketNumber":@10, @"name":@"alice",@"valueKey": @1.2 }];
/// Synchronize modfication
[[Flagship sharedInstance] synchronizeModificationsWithCompletion:^(enum FlagshipResult result) {
if (result == FlagshipResultUpdated){
/// Update UI ....
NSString * title = [[Flagship sharedInstance] getModification:@"bannerTitle" defaultString:@"More Infos" activate:YES];
}
}];
///update context with pre configured key
/// Set Region
Flagship.sharedInstance.updateContext(configuredKey: PresetContext.LOCATION_REGION, value: "ile de france")
/// Set Country
Flagship.sharedInstance.updateContext(configuredKey: PresetContext.LOCATION_COUNTRY, value: "FRANCE")
/// Add several pre configured key using the dictionary
Flagship.sharedInstance.updateContext([PresetContext.LOCATION_CITY.rawValue:"paris",
PresetContext.LOCATION_COUNTRY.rawValue:"France",
PresetContext.LOCATION_REGION.rawValue:"ile de france"])
Campaign synchronization
Synchronizing campaigns
Synchronizing campaign modifications allows you to automatically call the Flagship decision API (or bucketing file), which makes the allocation according to the user context and gets all their modifications.
All the modifications returned by the API (or by the bucketing file) are stored in the SDK and are updated asynchronously when synchronizeModifications() is called.
func synchronizeModifications(completion:@escaping((FlagshipResult)->Void))
Parameter | Type | Description |
---|---|---|
completion | code | Block to execute once the sync is completed |
FlagshipResult
indicates the state of the SDK as Updated or NotReady
- Updated: The SDK is Updated. You can get all new modifications according to contextValues.
- NotReady: An error occured at the update for some reason (See the logs). Only previous modifications before the update are still available.
Once the new values given by the Decision API are updated, the block below is executed.
// Here, for example, update VIP user info and adapt the UI...
// Update isVipUser with false value in the user context
[[Flagship sharedInstance] updateContext:@{@"isVipUser":@NO}];
/// Synchronize modfication
[[Flagship sharedInstance] synchronizeModificationsWithCompletion:^(enum FlagshipResult result) {
if (result == FlagshipResultUpdated){
dispatch_async(dispatch_get_main_queue(), ^{
// Update the UI
// Get title for banner
NSString * title = [[Flagship sharedInstance] getModification:@"bannerTitle" defaultString:@"More Infos" activate:YES];
// Set the title ...
});
}
}];
/// Update the context when basket value change
Flagship.sharedInstance.synchronizeModifications { (result) in
if result == .Updated{
// Update the UI for users that have basket over or equal 100
if (Flagship.sharedInstance.getModification("freeDelivery", defaultBool: false, activate: true)){
DispatchQueue.main.async {
/// Show your message for free delivery
}
}
}
}
Synchronizing Context Example
Here's a quick guide on how to manage a free delivery threshold for e-commerce. In this example, free delivery is triggered when basketValue
is greater than $100.
In your code, call the following function
/// Update context with "basketValue" = 120
Flagship.sharedlnstance.updateContext("basketValue", 120)
/// Synchronize campaigns
Flagship.sharedInstance.synchronizeModifications { (result) in
if result == .Updated{
/// Update the UI for users having basket's values greater than or equal to 100
if (Flagship.sharedlnstance.getModification("freeDelivery", defaultBool: false, activate: true)){
DispatchQueue.main.async {
/// Show message indicating free delivery threshold has been met
}
}
}
}
This function will ask the decision API and get the new modifications according to context passed as parameters.
Once the update is done, you can display the free delivery message, as described in the example above.
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:
-
Get Modification for Boolean value:
func getModification(_ key:String, defaultBool:Bool, activate:Bool) -> Bool
-
Get Modification for String value:
func getModification(_ key:String, defaultString:String, activate:Bool) -> String
-
Get Modification for Double value:
func getModification(_ key:String, defaultDouble:Double, activate:Bool) -> Double
-
Get Modification for Float value:
func getModification(_ key:String, defaulfloat:Float, activate:Bool) -> Float
-
Get Modification for Int value :
func getModification(_ key:String, defaultInt:Int, activate:Bool) -> Int
-
Get Modification for Json value:
func getModification(_ key:String, defaultJson:Dictionary<String,Any>, activate:Bool = false)->Dictionary<String,Any>
-
Get Modification for Array:
func getModification(_ key:String, defaultArray:[Any], activate:Bool = false)->[Any]
- If the Decision API doesn't return any value for a key, the SDK will display the default value.
- When the key value is a json object, the returned value will be a dictionary representing this json.
- When the key value is an array, the returned value will be an array.
Parameter | Type | Required | Description |
---|---|---|---|
key | String | Yes | key associated with the modification. |
default | String, Boolean, Int, Float, Double, Dictionary, Array | Yes | default value returned when the key doesn't match any modification value. |
activate | Boolean | No | false by default Set this parameter to true to automatically report on our server that the current visitor has seen this modification. If false, call the activateModification() later. |
An example of keys values defined in the variation 1
How to gets values:
// Retrieve modification and activate
NSString * title = [[Flagship sharedInstance] getModification:@"bannerTitle" defaultString:@"More Infos" activate:YES];
/// Get "cta_text"
let title = Flagship.sharedInstance.getModification("cta_text", defaultString: "default", activate: true)
/// Get "cta_vallue"
let value = Flagship.sharedInstance.getModification("cta_value", defaultInt: 0, activate: true)
/// Get "isHidden"
let isTrue = Flagship.sharedInstance.getModification("isHidden", defaultBool: false, activate: true)
Getting campaign information
You may need to send campaign's informations to a third-party for reporting and/or analytics purposes. The getModificationInfo
method returns a dictionary with values you can use.
These values are:
key | Type | Description |
---|---|---|
campaignId | String | id for the campaign |
variationGroupId | String | Id for the variation group |
variationId | String | id for variation selected |
isReference | Bool | if true that means the selected variation is a reference, otherwise not a reference. |
func getModificationInfo(_ key:String) -> [String:Any]?
Parameter | Type | Required | Description |
---|---|---|---|
key | String | Yes | key associated with the modification. |
- Return dictionary [String:Any]? 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
/// Get modification info
NSDictionary * dico = [[Flagship sharedInstance] getModificationInfoWithKey:@"btn-color"];
if (dico){
/// Get campaignid
NSString * campaignId = [dico valueForKey:@"campaignId"];
/// Get variation group id
NSString * variationGroupId = [dico valueForKey:@"variationGroupId"];
/// Get variation id
NSString * variationId = [dico valueForKey:@"variationId"];
/// Get the boolean for reference
BOOL isRef = [dico valueForKey:@"isReference"];
NSLog(@" %@ , %@, %@", campaignId, variationGroupId, variationId);
}else{
NSLog(@"The key modification doesn't exist.");
}
/// The get modificationInfo return [String:Any]?
/// ex: { “campaignId”: “xxxx”, “variationGroupId”: “xxxx“, “variationId”: “xxxx”, "isReference":true}
let infos = Flagship.sharedInstance.getModificationInfo(key:"btn-color")
if let infoCampaign = infos {
/// Retreive the campaignId
let campaignId = infoCampaign["campaignId"] as? String ?? "None"
/// Retreive the variationGroupId
let variationGroupId = infoCampaign["variationGroupId"] as? String ?? "None"
/// Retreive the variationId
let variationId = infoCampaign["variationId"] as? String ?? "None"
/// Retreive reference indicator
let isReference = infoCampaign["isReference"] as? Bool ?? false
print(campaignId + variationId + variationGroupId )
}else {
print("The key modification doesn't exist.")
}
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.
// Activate modification to tell Flagship that the user has seen this specific variation
[[Flagship sharedInstance] activateModificationWithKey:@"cta_text"];
// Activate modification to tell Flagship that the user has seen this specific variation
FlagShip.sharedInstance.activateModification(key: "cta_text")
func activateModification(key:String)
Parameter | Type | Required | Description |
---|---|---|---|
key | String | Yes | Modification identifier |
If the given modification key doesn't exist, the activate event will not be sent.
Get Modification and activate it manually:
/// Get "cta_value"
let value = Flagship.sharedInstance.getModification("cta_value" defaultlnt: 0)
/// Activate Manually
Flagship.sharedlnstance.activateModification(key: "cta_value")
Hit Tracking
This section helps you track your users in your application and learn how to build hits in order to feed campaign goals. For more information about our measurement protocol, read our Universal Collect documentation.
There are four different types of Hits available:
- Screen
- Transaction
- Item
- Event
They must all be sent with the following function:
func sendHit<T: FSTrackingProtocol>(_ event:T)
Common Parameters
These parameters can be sent with any type of hit.
Parameter | Type | Description |
---|---|---|
userIp | String | optional Current user IP address |
screenResolution | String | optional Screen Resolution |
userLanguage | String | optional User Language |
currentSessionTimeStamp | Int64 | optional Current Session Timestamp |
sessionNumber | Int | optional Session Number |
// Create event
FSScreen* eventScreen = [[FSScreen alloc] init:@"loginScreen"];
// Fill data for event screen
eventScreen.userIp = @"168.192.1.0";
eventScreen.sessionNumber = @12;
eventScreen.screenResolution = @"750 x 1334";
eventScreen.screenColorDepth = @"#fd0027";
eventScreen.sessionNumber = @1;
eventScreen.userLanguage = @"fr";
eventScreen.sessionEventNumber = @2;
[[Flagship sharedInstance] sendScreenEvent:eventScreen];
// Create event
let eventScreen = FSScreen("loginScreen")
// Fill data for event screen
eventScreen.userIp = "168.192.1.0"
eventScreen.sessionNumber = 12
eventScreen.screenResolution = "750 x 1334"
eventScreen.screenColorDepth = "#fd0027"
eventScreen.sessionNumber = 1
eventScreen.userLanguage = "fr"
eventScreen.sessionEventNumber = 2
// Send Event
Flagship.sharedInstance.sendHit(eventScreen)
Screen
This hit should be sent each time a visitor arrives on a new interface.
The FSScreen class represents this hit and it requires location
as a string parameter.
// Usage: this hit is usually sent when changing screens in the app
// Create screen event
FSScreen * eventScreen = [[FSScreen alloc] init:@"loginScreen"];
// Send Event
[[Flagship sharedInstance] sendScreenEvent:eventScreen];
// Usage: this hit is usually sent when changing screens in the app
let eventScreen = FSScreen("loginScreen")
Flagship.sharedInstance.sendHit(eventScreen)
Transaction
Hit to send when a user completes a Transaction.
FSTransaction represents it and requires a unique transactionId
and affiliation
name. affiliation
is the name of the transaction goal.
// The affiliation is the name of transaction that should appear in the report
// Create the transaction event
FSTransaction * transacEvent = [[FSTransaction alloc] initWithTransactionId:@"transacId" affiliation:@"BasketTransac"];
transacEvent.currency = @"EUR";
transacEvent.itemCount = 0;
transacEvent.paymentMethod = @"PayPal";
transacEvent.shippingMethod = @"Fedex";
transacEvent.tax = @2.6;
transacEvent.revenue = @15;
transacEvent.shipping = @3.5;
// Send the transaction event
[[Flagship sharedInstance] sendTransactionEvent:transacEvent];
// The affiliation is the name of transaction that should appear in the report
let transacEvent:FSTransaction = FSTransaction(transactionId:"transacId", affiliation:"BasketTransac")
transacEvent.currency = "EUR"
transacEvent.itemCount = 0
transacEvent.paymentMethod = "PayPal"
transacEvent.shippingMethod = "Fedex"
transacEvent.tax = 2.6
transacEvent.revenue = 15
transacEvent.shipping = 3.5
FlagShip.sharedInstance.sendHit(transacEvent)
init(transactionId:String, affiliation:String)
Parameter | Type | Required | Description |
---|---|---|---|
transactionId | String | required | Transaction unique identifier. |
affiliation | String | required | Transaction name. Name of the goal in the reporting. |
revenue | Float | optional | Total revenue associated with the transaction. This value should include any shipping or tax costs. |
shipping | Float | optional | Specifies the total shipping cost of the transaction. |
tax | Float | optional | Specifies the total taxes of the transaction. |
currency | String | optional | Specifies the currency used for all transaction currency values. Value should be a valid ISO 4217 currency code. |
paymentMethod | String | optional | Specifies the payment method for the transaction. |
shippingMethod | String | optional | Specifies the shipping method of the transaction. |
itemCount | Int | optional | Specifies the number of items for the transaction. |
couponCode | String | optional | Specifies the coupon code used by the customer for the transaction. |
Item
Hit to send an item with a transaction. It must be sent after the corresponding transaction.
FSItem represents this hit and requires transactionId
and product name.
// Create item event
FSItem * itemhit = [[FSItem alloc] initWithTransactionId:@"transacId" name:@"MicroTransac" code:@"codeSku"];
/// Set Price
itemhit.price = @20;
/// Set category
itemhit.category = @"category";
/// Set quantity
itemhit.quantity = @1;
/// Send item event
[[Flagship sharedInstance] sendItemEvent:itemhit];
// Item usually represents a product. An item must be associated with a transaction event.
/// Create item hit
let itemHit = FSItem(transactionId: "idTransaction", name: "itemName", code: "codeSku")
/// Set price
itemHit.price = 20
/// set category
itemHit.category = "shoes"
/// set quantity
itemHit.quantity = 2
/// Send Item
Flagship.sharedInstance.sendHit(itemHit)
init(transactionId:String, name:String, code:String)
Parameter | Type | Required | Description |
---|---|---|---|
transactionId | String | required | Transaction unique identifier |
name | String | required | Product name |
price | Float | optional | Specifies the item price |
code | String | required | Specifies the item code or SKU |
category | String | optional | Specifies the item category |
quantity | Int | optional | Specifies the item quantity |
Info
The
FSItem
hit isn't available yet in the Flagship reporting view.
Event
Hit which represents an event. It can be anything you want: for example a click on an Add to Cart button or a newsletter subscription.
FSEvent represents this hit and requires a category event and action name string.
FSCategoryEvent can be Action_Tracking
or User_Engagement
.
// Create event for any user action
// The event action is the name to display in the report
FSEvent * actionEvent = [[FSEvent alloc] initWithEventCategory:FSCategoryEventAction_Tracking eventAction:@"cta_Shop"];
actionEvent.label = @"cta_Shop_label";
actionEvent.eventValue = @1;
[[Flagship sharedInstance] sendEventTrack:actionEvent];
// Create event for any user action
// The event action is the name to display in the report
let actionEvent:FSEvent = FSEvent(eventCategory: FSCategoryEvent.Action_Tracking, eventAction: "cta_Shop")
actionEvent.label = "cta_Shop_label"
actionEvent.eventValue = 1
// Send Event Tracking
FlagShip.sharedInstance.sendHit(actionEvent)
Parameter | Type | Required | Description |
---|---|---|---|
category | FSCategoryEvent | required | Category of the event (Action_Tracking or User_Engagement ). |
action | String | required | Name of the event. |
label | String | optional | Description of the event. |
eventValue | Number | optional | Value of the event must be a non-negative number. |
Logs
Logs are enabled by default. If you want to stop logs, set enableLogs
to false
.
[[Flagship sharedInstance] setEnableLogs:NO];
Flagship.sharedInstance.enableLogs = false
Release notes
2.0.4 (Latest version)
Changed
- Change Page hit for Screen hit.
- interfaceName attribute removed for hits (Event, Transaction, Item) except Screen hit
2.0.3
Fixed
- Remove header from api call to events and activate endpoints.
2.0.2
Added
isReference
value in getModificationInfo function
Fixed
- Targeting on lists
2.0.1
Fixed
- Send activate event through getModification function for json and array
2.0.0
Added
- New Start function with a mandatory parameter apiKey and optional Configuration
- Remove all deprecated functions
- Add customizable timeout when fetching campaigns under API Mode
- The get modification function handle a complex object (json, array)
Fixed
- Improve the MurMurHash algorithm
Appendix
Predefined user context keys
The Flagship SDK contains predefined user context keys.
The keys marked as Yes in the Auto-set by SDK column will be automatically set, while the ones marked as No need to be set by the client.
They are nevertheless overridable at anytime. Then these predefined context keys-value pairs will be sent to the server and be editable in the Persona section of the Flagship platform.
SDK Variable name | Description | Context Variable name | Type | Auto-set by SDK | Example |
---|---|---|---|---|---|
FIRST_TIME_INIT | First init of the app | sdk_firstTimeInit | Boolean | Yes | true (false if the init isn’t the first one) |
LOCALE | Language of the device | sdk_deviceLanguage | String | Yes | fr_FR |
DEVICE_TYPE | Type fo the device (Tablet/Mobile) | sdk_deviceType | String | Yes | mobile |
LOCATION_CITY | City geolocation | sdk_city | String | No | toulouse |
LOCATION_REGION | Region geolocation | sdk_region | String | No | occitanie |
LOCATION_COUNTRY | Country geolocation | sdk_country | String No | France | |
LOCATION_LAT | Current Latitude | sdk_lat | Double | No | 43.623647 |
LOCATION_LONG | Current Longitude | sdk_long | Double | No | 1.445397 |
IP | IP of the device | sdk_ip | String | No | 127.0.0.1 |
OS_NAME | Name of the OS | sdk_osName | String | Yes | iOS |
IOS_VERSION | Version of iOS | sdk_iOSVersion | String | Yes | 9 |
MVNO / carrierName | (Mobile virtual network operator)" | Name of the operator | sdk_carrierName | String | Yes |
DEV_MODE | Is the app in debug mode? | sdk_devMode | Boolean | No | true |
INTERNET_CONNECTION | What is the internet connection | sdk_internetConnection | String | No | 3g |
APP_VERSION_NAME | Version name of the app | sdk_versionName | String | No | 1.1.2-beta |
APP_VERSION_CODE | Version code of the app | sdk_versionCode | Number (int) | No | 40 |
FLAGSHIP_VERSION | Version of the Flagship SDK | sdk_fsVersion | String | Yes | 1.1.2 |
INTERFACE_NAME | Name of the interface | sdk_interfaceName | String | No | ProductPage |
To overwrite the keys, use the
updateContext
method
Here you can see how a predefined key is used to filter a report in the Flagship interface:
Updated 6 months ago