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:

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

Getting Started

Our Flagship iOS SDK is available for distribution through CocoaPods, Swift Package Manager or manual installation.

Cocoapods

  1. Install CocoaPods

  2. Open Terminal and browse to the directory that contains your project then, enter the following command: pod init

  3. Open your Podfile and add the following line to the Podfile

target 'Your App' do
    use_frameworks!

    pod 'FlagShip'

    end
  1. Run pod install from your Xcode project's base directory

  2. Make sure you always open the Xcode workspace and not the project file when building your project

Manual Installation

  1. Download the Flagship framework

  2. In Finder, browse to the Flagship.framework file and move it under your "Embedded Binaries" section in Xcode

  3. 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.

Swift Package Manager video tutorial

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)

ParameterTypeRequiredDescription
envIdStringYesIdentifies your Flagship account and environment (preprod or prod). Find this ID
apiKeyStringYesIdentifies your Flagship api key (preprod or prod). Find this api key
visitorIdStringYesUnique 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
configFSConfigNoObject that represent configuration client. Default values are (DECISION_API for the mode and 2 seconds for the api timeout)
onStartDoneblockYesIndicates 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.

  1. Navigate to ParametersEnvironment & Security
  2. 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.

994

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)

ParameterTypeRequiredDescription
modeFlagshipModeNoapi or bucketing. The default value is DECISION_API
timeoutTimeIntervalNotimeout 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 the synchronizeModifications 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.

994

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)

ParameterTypeRequiredDescription
keyStringYesAttribute key associated with the following value
valueString, Double, Boolean, FLoatYesAttribute value to add in the context
  • Add Dictionary to the user context:

func updateContext(_ contextValues:Dictionary<String,Any>)

ParameterTypeRequiredDescription
contextValuesdictionaryYesDictionary 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)

ParameterTypeRequiredDescription
configuredKeyPresetContextYesThe values defined in an enumeration PresetContext
valueString, Double, Boolean, FLoatYesthe 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))

ParameterTypeDescription
completioncodeBlock 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.

1005

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.
ParameterTypeRequiredDescription
keyStringYeskey associated with the modification.
defaultString, Boolean, Int, Float, Double, Dictionary, ArrayYesdefault value returned when the key doesn't match any modification value.
activateBooleanNofalse 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

1001

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:

keyTypeDescription
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.

func getModificationInfo(_ key:String) -> [String:Any]?

ParameterTypeRequiredDescription
keyStringYeskey 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)

ParameterTypeRequiredDescription
keyStringYesModification 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.

ParameterTypeDescription
userIpStringoptional Current user IP address
screenResolutionStringoptional Screen Resolution
userLanguageStringoptional User Language
currentSessionTimeStampInt64optional Current Session Timestamp
sessionNumberIntoptional 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)

ParameterTypeRequiredDescription
transactionIdStringrequiredTransaction unique identifier.
affiliationStringrequiredTransaction name. Name of the goal in the reporting.
revenueFloatoptionalTotal revenue associated with the transaction. This value should include any shipping or tax costs.
shippingFloatoptionalSpecifies the total shipping cost of the transaction.
taxFloatoptionalSpecifies the total taxes of the transaction.
currencyStringoptionalSpecifies the currency used for all transaction currency values. Value should be a valid ISO 4217 currency code.
paymentMethodStringoptionalSpecifies the payment method for the transaction.
shippingMethodStringoptionalSpecifies the shipping method of the transaction.
itemCountIntoptionalSpecifies the number of items for the transaction.
couponCodeStringoptionalSpecifies 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)

ParameterTypeRequiredDescription
transactionIdStringrequiredTransaction unique identifier
nameStringrequiredProduct name
priceFloatoptionalSpecifies the item price
codeStringrequiredSpecifies the item code or SKU
categoryStringoptionalSpecifies the item category
quantityIntoptionalSpecifies 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)
ParameterTypeRequiredDescription
categoryFSCategoryEventrequiredCategory of the event (Action_Tracking or User_Engagement).
actionStringrequiredName of the event.
labelStringoptionalDescription of the event.
eventValueNumberoptionalValue 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 DescriptionContext Variable nameTypeAuto-set by SDKExample
FIRST_TIME_INITFirst init of the appsdk_firstTimeInitBooleanYestrue (false if the init isn’t the first one)
LOCALE Language of the devicesdk_deviceLanguageStringYesfr_FR
DEVICE_TYPEType fo the device (Tablet/Mobile) sdk_deviceTypeStringYes mobile
LOCATION_CITYCity geolocationsdk_cityStringNotoulouse
 LOCATION_REGIONRegion geolocationsdk_regionStringNooccitanie
LOCATION_COUNTRYCountry geolocationsdk_countryString NoFrance
LOCATION_LATCurrent Latitudesdk_latDoubleNo43.623647
LOCATION_LONGCurrent Longitudesdk_longDoubleNo1.445397
IPIP of the devicesdk_ipStringNo127.0.0.1
OS_NAMEName of the OSsdk_osNameStringYesiOS
IOS_VERSIONVersion of iOSsdk_iOSVersionStringYes9
MVNO / carrierName(Mobile virtual network operator)"Name of the operatorsdk_carrierNameStringYes
DEV_MODEIs the app in debug mode?sdk_devModeBooleanNotrue
INTERNET_CONNECTIONWhat is the internet connectionsdk_internetConnectionStringNo3g
APP_VERSION_NAMEVersion name of the appsdk_versionNameStringNo1.1.2-beta
APP_VERSION_CODEVersion code of the appsdk_versionCodeNumber (int)No40
FLAGSHIP_VERSIONVersion of the Flagship SDKsdk_fsVersionString Yes1.1.2
INTERFACE_NAMEName of the interfacesdk_interfaceNameStringNoProductPage

📘

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:

2426