.NET V3.0.X
Introduction
The following documentation will help you get Flagship running in your .Net environment (server-side or client side) with preconfigured methods to implement the Decision API & Bucketing.
Feel free to contact us if you have any questions regarding this documentation.
SDK features
That SDK version helps you :
- Set a visitor ID
- Update user context
- Assign campaigns via the Decision API or the Bucketing
- Get flags
- Activate campaigns
- Send hits to our Universal Collect
Prerequisites
- This SDK requires .Net with the following target framework versions:
- net40
- net45
- netstandard2.0
- net5.0 or later
- Your server/device must have an access to the internet.
Good to know
- Github repository: https://github.com/flagship-io/flagship-dotnet-sdk
Getting Started
Installation
Follow these steps to install the .Net SDK
Install from nuget
To install from nuget, just run a Install-Package
Nuget command to add the SDK to your project
Install-Package Flagship.SDK
Initialization
To initialize and start the SDK, simply call the Start
function of the Flagship.Main.Fs
class, in the most appropriate location for your application.
// Use the Flagship package
using Flagship.Main;
// ...
Fs.Start("ENV_ID", "API_KEY");
Start
static function
Start
static functionThat method start the Flagship SDK.
static void Start(string envId, string apiKey, [FlagshipConfig config = null])
Parameter | Type | Description |
---|---|---|
envId | string | Environment id provided by Flagship. |
apiKey | string | Api authentication key provided by Flagship. |
config | FlagshipConfig | Custom flagship configuration. see configuration attribute |
Advanced Configuration
Here are all available settings you can set on the SDK.
Those settings can be setup only at the start function.
Here's the full pure example of usage :
// Use the Flagship package
using Flagship.Main;
// ...
Fs.Start("ENV_ID", "API_KEY", new DecisionApiConfig {
LogManager = new sentryCustomLog(),
LogLevel = Flagship.Enums.LogLevel.ALL,
Timeout = TimeSpan.FromSeconds(2),
});
// Use the Flagship package
using Flagship.Main;
// ...
Fs.Start("ENV_ID", "API_KEY", new BucketingConfig {
LogManager = new sentryCustomLog(),
LogLevel = Flagship.Enums.LogLevel.ALL,
Timeout = TimeSpan.FromSeconds(2),
PollingInterval = TimeSpan.FromSeconds(2)
});
Below the details of every attribute you can set inside the SDK config object :
Attribute | Type | Default | Description |
---|---|---|---|
Timeout | TimeSpan | 2s | Required Specify timeout for api request. Note: timeout can't be lower than 0 second. |
LogLevel | Flagship.Enums.LogLevel | Flagship.Enums.LogLevel.ALL | Required Set the maximum log level to display see LogLevel |
LogManager | Flagship.Logger.IFsLogManager | Oject | Required Specify a custom implementation of LogManager in order to receive logs from the SDK. Note: The object must fill Interface IFsLogManager |
PollingInterval | TimeSpan | 2s | Required Specify delay between two bucketing polling when SDK is running on Bucketing mode. Note: If 0 is given, it should poll only once at start time. |
VisitorCacheImplementation | Flagship.Cache.IVisitorCacheImplementation | undefined | Optional Define an object that implement the interface IVisitorCacheImplementation , to handle the visitor cache. see cache-manager |
HitCacheImplementation | Flagship.Cache.IHitCacheImplementation | undefined | Optional Define an object that implement the interface IHitCacheImplementation , to handle the visitor cache. see cache-manager |
DisableCache | boolean | false | Required if it's set to true, hit cache and visitor cache will be disabled otherwise will be enabled. see cache-manager |
StatusChanged | Flagship.Delegate.StatusChangeDelegate | undefined | Optional Define a callable in order to get callback when the SDK status has changed. see arguments. |
Decision Mode
API
Mode (by default)
When the SDK is running in API
mode, the campaign assignments and targeting validation will be run through our Decision API. In this mode, each time a new Decision is required, it will create an HTTPS request to the API.
This mode is used by default for all our SDK.
Bucketing
Mode
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
LogLevel
Flagship.Enums.LogLevel
is an enum defined the level of log to receive
Key | Value | Type | Description |
---|---|---|---|
NONE | 0 | int | Logging will be disabled. |
EMERGENCY | 1 | int | Only emergencies will be logged |
ALERT | 2 | int | Only alerts and above will be logged. |
CRITICAL | 3 | int | Only critical and above will be logged. |
ERROR | 4 | int | Only errors and above will be logged. |
WARNING | 5 | int | Only warnings and above will be logged. |
NOTICE | 6 | int | Only notices and above will be logged. |
INFO | 7 | int | Only info logs and above will be logged. |
DEBUG | 8 | int | Only debug logs and above will be logged. |
ALL | 9 | int | Everything will be logged. |
IFsLogManager
The aims of Flagship.Logger.IFsLogManager
Interface is to define methods that an object must have in order to receive Flagship SDK logs.
interface IFsLogManager
{
void Emergency(string message, string tag);
void Alert(string message, string tag);
void Critical(string message, string tag);
void Error(string message, string tag);
void Warning(string message, string tag);
void Notice(string message, string tag);
void Info(string message, string tag);
void Debug(string message, string tag);
void Log(LogLevel level, string message, string tag);
}
Argument | Type | Description |
---|---|---|
message | string | Get a description of the log |
tag | string | Get the function that triggered the log |
level | number | Get the log level. Note:only for log method see LogLevel |
FlagshipStatus
Flagship.Enums.FlagshipStatus
is an enum defining the different status of Flagship SDK
Key | Value | Type | Description |
---|---|---|---|
NOT_INITIALIZED | 0 | int | It is the default initial status. This status remains until the sdk has been initialized successfully. |
STARTING | 1 | int | Flagship SDK is starting. |
POLLING | 2 | int | Flagship SDK has been started successfully but is still polling campaigns. |
READY_PANIC_ON | 3 | int | Flagship SDK is ready but is running in Panic mode: All features are disabled except the one which refresh this status. |
READY | 4 | int | Flagship SDK is ready to use. |
StatusChanged
The Flagship.Delegate.StatusChangeDelegate
delegate has one argument
Argument | Type | Description |
---|---|---|
status | Flagship.Enums.FlagshipStatus | Status of the SDK. seeFlagshipStatus |
Other Flagship.Main.Fs
class methods
Flagship.Main.Fs
class methodsStatus
property
Status
propertyReturn current status of Flagship SDK. seeFlagshipStatus
static FlagshipStatus Status
Config
property
Config
propertyReturn the current config used by the SDK. see configuration attribute
FlagshipConfig Config
Visitor
property
Visitor
propertyReturn the last visitor created and saved or return undefined if no visitor has been saved. see newVisitor.
static Visitor Visitor
Create a visitor
The Flagship.FsVisitor.Visitor
instance is an object that contains everything related to your visitor, its data but also the Decision of Flagship.
By creating a new visitor, you be able to set all the data relevant for Flagship to take a Decision and know your visitor, this includes :
- Visitor ID
- Visitor Context
- GDPR Consent
- Authenticated or not (see Experience Continuity) feature
The visitor context is a dataset (object) that defines your current visitor.
This dataset is sent to Flagship for targeting purposes (use-case assignment) but also to enrich your reporting with Context Filters.
You may have to sync with your team to know what data is useful for them to have in Flagship reporting.
By default, depending on Flagship.Config.FlagshipConfig
, this will automatically trigger a Decision of Flagship and will be available through the getFlag method.
Let's take an example:
if you want to enable a specific feature to all your VIPs
user,
you'll need to add this data as an attribute into the visitor context (key-value pair) in the visitor context: isVIP: true
.
Based on your targeting criteria defined in your use-case (isVIP === true
), Flagship will take the Decision and show your feature to visitors that at least contains isVIP
in their context and for which isVIP
is equal to true
.
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
NewVisitor
static function
NewVisitor
static functionCreates and returns a Flagship.FsVisitor.VisitorBuilder
or null
if the SDK hasn't started successfully.
This method should always be called after the Flagship SDK has started.
static VisitorBuilder NewVisitor()
Initialize the builder without visitorID
and Return a Flagship.FsVisitor.VisitorBuilder
or null if the SDK hasn't started successfully.
static VisitorBuilder NewVisitor(string visitorId)
Initialize the builder with visitorId
and Return a Flagship.FsVisitor.VisitorBuilder
or null if the SDK hasn't started successfully.
Parameter | Type | Description |
---|---|---|
visitorId | string | Unique visitor identifier |
static VisitorBuilder NewVisitor(InstanceType instanceType)
Initialize the builder with InstanceType
and Return a Flagship.FsVisitor.VisitorBuilder
or null if the SDK hasn't started successfully.
Parameter | Type | Description |
---|---|---|
InstanceType | Flagship.Enums.InstanceType | Defined if the SDK will save the newly created visitor instance into the Flagship instance |
static VisitorBuilder NewVisitor(string visitorId, InstanceType instanceType)
Initialize the builder with visitorId
and InstanceType
and Return a Flagship.FsVisitor.VisitorBuilder
or null if the SDK hasn't started successfully.
Parameter | Type | Description |
---|---|---|
visitorId | string | Unique visitor identifier. |
InstanceType | Flagship.Enums.InstanceType | Defined if the SDK will save the newly created visitor instance into the Flagship instance |
VisitorBuilder
Flagship.FsVisitor.VisitorBuilder
is a fluent interface builder api managing Visitor creation.
-
VisitorBuilder IsAuthenticated(bool isAuthenticated)
Specify if the Visitor is authenticated or anonymous.
Parameter | Type | Description |
---|---|---|
isAuthenticated | bool | true for an authenticated visitor, false for an anonymous visitor. |
-
VisitorBuilder HasConsented(bool hasConsented)
Specify if the Visitor has consented for personal data usage. When false some features will be deactivated, cache will be deactivated and cleared.
Parameter | Type | Description |
---|---|---|
hasConsented | bool | Set to true when the visitor has consented, false otherwise. |
-
VisitorBuilder WithContext(IDictionary<string, object> context)
Specify Visitor initial context key / values used for targeting.
Parameter | Type | Description |
---|---|---|
withContext | IDictionary<string, object>| | visitor initial context. |
- User context keys must have a type of
string
- User context values must have a type of
string
,bool
,numeric
- User context keys and values are case sensitive
-
Visitor Build()
Complete the Visitor Creation process and return an instance of
\Flagship\Visitor\Visitor
- If visitorId is not given, the SDK will generat one by default
- If IsAuthenticated is not set, the SDK will set
false
by default- If HasConsented is not set, the SDK will set
true
by default
Updating the visitor context
The user context is a property dataset that defines the current user of your app. This dataset is sent and used as targeting criteria for campaign assignment.
The following method from the Flagship.FsVisitor.Visitor
instance allows you to set new context values matching the given keys.
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
visitor.UpdateContext("lastPurchaseDate", DateTime.Now.ToShortDateString());
updateContext
function
updateContext
functionUpdate the visitor context values, matching the given keys, used for targeting.
A new context value associated with this key will be created if there is no previous matching value.
void UpdateContext(IDictionary<string, object> context)
It has one argument :
Argument | Type | Description |
---|---|---|
context | IDictionary<string, object> | A Set of keys, values. |
void UpdateContext(string key, string value)
Update the visitor context values, matching the given key or created one if there is no previous matching value
Parameter | Type | Description |
---|---|---|
key | string | Context key. |
value | string | Context value. |
void UpdateContext(string key, double value)
Update the visitor context values, matching the given key or created one if there is no previous matching value
Parameter | Type | Description |
---|---|---|
key | string | Context key. |
value | double | Context value. |
void UpdateContext(string key, bool value)
Update the visitor context values, matching the given key or created one if there is no previous matching value
Parameter | Type | Description |
---|---|---|
key | string | Context key. |
value | bool | Context value. |
Context
property
Context
propertyThis property returns all the visitor's current context as an object
- `IDictionary<string, object> Context
ClearContext
function
ClearContext
functionClear the actual visitor context
void ClearContext()
- User context keys must have a type of
string
- User context values must have a type of
string
,bool
,numeric
- User context keys and values are case sensitive
update context with predefined keys of context
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
visitor.UpdateContext(Flagship.Enums.PredefinedContext.OS_NAME, "linux");
visitor.UpdateContext(Flagship.Enums.PredefinedContext.IP, "127.0.0.1");
Learn more about predefined keys of context
Managing visitor campaigns
Fetching Flags
The FetchFlags()
method of the Visitor
instance, according to Decision Mode, will either automatically call the Flagship Decision API to run campaign assignments according to the current user context and retrieve applicable flags,
or check bucketing file
, validate campaigns targeting the visitor, assign a variation and retrieve applicable flags
These flags are then stored in the SDK and updated asynchronously when FetchFlags()
is called.
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
await visitor.FetchFlags();
//ready to use all features from the SDK
FetchFlags
function
FetchFlags
functionIn DecisionApi Mode this function calls the Flagship Decision API to run campaign assignments according to the current user context and retrieve applicable flags.
In bucketing Mode, it checks bucketing file, validates campaigns targeting the visitor, assigns a variation, and retrieves applicable flags
Task FetchFlags()
Getting flags
Once the campaign has been assigned and fetched, all the flags are stored in the SDK. You can retrieve them using the following functions from the Visitor
instance:
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
await visitor.FetchFlags();
var flag = visitor.GetFlag("displayVipFeature", false);
GetFlag
function
GetFlag
functionReturn 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.
IFlag<T> GetFlag(string key, T defaultValue)
Argument | Type | Description |
---|---|---|
key | string | key associated to the flag. |
defaultValue | T | flag default value. |
- Default value must be one of the following type :
string
,number
,boolean
,Newtonsoft.Json.Linq.JArray
,Newtonsoft.Json.Linq.JObject
.
Getting flags current values
GetValue
function
GetValue
functionTo retrieve flag current value, simply call GetValue() method of the Flag object.
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
await visitor.FetchFlags();
var flag = visitor.GetFlag("displayVipFeature", false);
var flagValue = flag.GetValue();
T GetValue([bool userExposed=true])
function
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 | Boolean | 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 sees it. |
Getting flags campaigns metadata
Metadata
property
Metadata
propertyYou may need to send campaign IDs or variation IDs to a third party for reporting and/or analytics purposes. It is possible to retrieve campaigns metadata for a specific Flag.
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
await visitor.FetchFlags();
var flag = visitor.GetFlag("displayVipFeature", false);
var campaignMetadata = flag.Metadata;
IFlagMetadata Metadata { get; }
Return the campaign information 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.
interface IFlagMetadata
{
string CampaignId { get; }
string CampaignName { get; }
string VariationGroupId { get; }
string VariationGroupName { get; }
string VariationId { get; }
string VariationName { get; }
bool IsReference { get; }
string CampaignType { get; }
string Slug { get; }
string ToJson();
}
Key\Property | Type | Description |
---|---|---|
CampaignId | string | Campaign name |
CampaignName | string | Campaign name |
VariationGroupId | string | Variation group ID |
VariationGroupName | string | Variation group name |
VariationId | string | The variation ID assigned to the user |
VariationName | string | Variation name |
IsReference | boolean | Specify if its the reference variation |
CampaignType | string | campaign type |
Slug | string | campaign slug |
ToJson | function | Return a Json of current metada |
Report a Flag exposition
UserExposed
function
UserExposed
functionBy default when the method GetValue() is called, The SDK considers that the user have seen the effets of your Flag, unless you pass false to GetValue(). In this case you will have to call UserExposed().
There are two ways for exposing a user to a flag:
- Pass an
UserExposed=true
parameter to the GetValue() method. - Use the following UserExposed() method from the Flag instance.
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
await visitor.FetchFlags();
//Get flag displayVipFeature
var flag = visitor.GetFlag("displayVipFeature", false);
var flagValue = flag.GetValue(false);
//Report a flag exposition
await flag.UserExposed();
Task UserExposed()
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. No user exposition will be sent if the Flag doesn't exist or if the default value type do not correspond to the Flag type in Flagship.
Check if a Flag exists
Exists
property
Exists
propertyThis method will return true if a Flag exists in Flagship
bool Exists { get; }
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true)
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
await visitor.FetchFlags();
//Get flag displayVipFeature
var flag = visitor.GetFlag("displayVipFeature", false);
var isDisplayVipFeature = flag.Exists();
Managing visitor consent
The Visitor
class provides a method to let you manage visitor consent for data privacy usage. When False, campaign activation and hits will be disabled.
There are 2 ways to set visitor consent :
- Set
HasConsented
to true when creating a new visitor - Use
SetConsent
method of visitor instance
using Flagship.Main;
//...
var visitor = Fs.NewVisitor("<VISITOR_ID>")
.IsAuthenticated(true)
.HasConsented(true) // set hasConsented to true
.WithContext(new Dictionary<string, object> {
["isVIP"] = true,
["country"] = "NL",
["loginProvider"] = "Google"
})
.Build();
// or use setConsent method
visitor.SetConsent(true);
SetConsent
function
SetConsent
functionSet if visitor has consented for protected data usage.
void SetConsent(bool hasConsented)
Argument | Type | Default | Description |
---|---|---|---|
hasConsented | boolean | required | Set visitor consent for private data usage. When false some features will be deactivated. |
hasConsented
property
hasConsented
propertyReturn True if the visitor has consented for private data usage, otherwise return False.
bool HasConsented { get; }
Experience Continuity
Dealing with anonymous and logged-in users, Experience continuity allows you to maintain consistency between sessions and devices.
Make sure that the experience continuity option is enabled on the flagship platform before using those methods.
Authenticate
There are 2 ways to authenticate a visitor:
- Set IsAuthenticated to true when creating a new visitor
- Use Authenticate of method of
Visitor
instance
Authenticate anonymous visitor
void Authenticate(string visitorId)
Argument | Type | Default | Description |
---|---|---|---|
visitorId | string | required | id of the new authenticated visitor. |
Because we have changed the visitor data, we have to call the fetchFlags method after calling this one to update the decision from Flagship.
The targeting / Flags could be different for the visitor.
Unauthenticate
This function change authenticated Visitor to anonymous visitor
void Unauthenticate()
Because we have changed the visitor datas, we have to call the fetchFlags method after calling this one to update the decision from Flagship.
The targeting / Flags could be different for the visitor.
Code example
Let's assume basic scenario to understand how things work:
1. Your visitor arrives on your app for the first time
We need to initialize the visitor but as we don't known anything about this visitor, we'll create a random visitor id or let the SDK do it for us. You can also specify some visitor context if necessary.
using Flagship.Main;
//...
var visitor = Fs.NewVisitor()
.WithContext(new Dictionary<string, object> {
["key"] = "value"
})
.Build();
visitor.fetchFlags()
Here we don't set visitorId property so the SDK has auto-created an id for our visitor.
Regardless of how it has been set, the actual visitor id will be what we call the anonymous id.
2. Your visitor is signing in.
To tell the SDK about this status modification, you'll have to call the authenticate function which takes the required visitor id as argument.
// Example
// You fetch the visitor_id from your DB
// let visitorId = db.getUserId();
visitor.Authenticate("VISITOR_ID_ALREADY_KNOWN_BY_FLAGSHIP");
// Since your visitor has changed (is now logged-in)
// You have to check if the proper targeting and flags are set
visitor.fetchFlags()
The visitor is updated as authenticated, keeping the previous variations from campaigns that are still matched and thus gives you same flags as before being logged in.
Keep in mind that if the visitor also has its context changed, you might still have changes on flags as your visitor might target new campaigns.
3. Your visitor decide to sign out.
If you want to keep the same visitor experience, then you should do:
visitor.Unauthenticate();
// Since your visitor has changed (is now logged-out)
// You have to check if the proper targeting and flags are set
visitor.fetchFlags();
Hit Tracking
This section helps you track your users in your application and learn how to build hits in order to feed your reports. For more information about our measurement protocol, read our Universal Collect documentation.
There are five different types of Hits available:
Class | Description |
---|---|
Page | User has seen a URL. |
Screen | User has seen a screen. |
Transaction | User has made a transaction. |
Item | Item bought in a transaction. |
Event | User has made a specific action. |
They must all be built and sent with the following function from the Visitor
instance:
await visitor.SendHit(new Screen("abtastylab"));
sendHit
function
sendHit
functionSend Hit to Flagship servers for reporting.
Task SendHit(HitAbstract hit)
Parameter | Type | Default | Description |
---|---|---|---|
hit | HitAbstract | required | Hit to send. see Hit |
Hit common optional parameters
await visitor.SendHit(new Screen("abtastylab")
{
UserIp = "127.0.0.1",
ScreenResolution= "800X600",
Locale = "fr",
SessionNumber = "1234"
});
Parameter | Type | Description |
---|---|---|
UserIp | string | (Optional) User IP |
ScreenResolution | string | (Optional) Screen resolution. |
Locale | string | (Optional) User language |
SessionNumber | string | (Optional) Session number |
Page
This hit should be sent each time a visitor arrives on a new page.
await visitor.SendHit(new Page("https://www.my_domain_com/my_page"));
- Constructor
Params | Type | Description |
---|---|---|
documentLocation | string | Valid url. |
- A hit of type
Page
has this following structure:
Property | Type | Description |
---|---|---|
DocumentLocation | string | Valid url. |
Screen
This hit should be sent each time a visitor arrives on an interface on client side.
await visitor.SendHit(new Screen("home_screen"));
- Constructor
Params | Type | Description |
---|---|---|
documentLocation | string | Screen name. |
- A hit of type
Screen
has this following structure:
Property | Type | Description |
---|---|---|
DocumentLocation | string | Screen name. |
Transaction
This hit should be sent when a user complete a Transaction.
await visitor.SendHit(new Transaction("#12345", "affiliation")
{
Taxes = 19.99,
Currency = "USD",
CouponCode = "code",
ItemCount = 1,
ShippingMethod = "road",
ShippingCosts = 5,
PaymentMethod = "credit_card",
TotalRevenue = 199.99
});
- Constructor
Params | Type | Description |
---|---|---|
transactionId | string | Unique identifier for your transaction. |
affiliation | string | The name of the KPI that you will have inside your reporting. Learn more |
- A hit of type
Transaction
has this following structure:
Property | Type | Description |
---|---|---|
TransactionId | string | Unique identifier for your transaction. |
Affiliation | string | The name of the KPI that you will have inside your reporting. Learn more |
TotalRevenue | double | Specifies the total revenue associated with the transaction. This value should include any shipping and/or tax amounts. |
ShippingCosts | double | The total shipping cost of your transaction. |
ShippingMethod | string | The shipping method for your transaction. |
Taxes | double | Specifies the total amount of taxes in your transaction. |
Currency | string | Specifies the currency of your transaction. NOTE: This value should be a valid ISO 4217 currency code. |
PaymentMethod | string | Specifies the payment method used for your transaction. |
ItemCount | int | Specifies the number of items in your transaction. |
CouponCode | string | Specifies the coupon code used by the customer in your transaction. |
Item
This hit is used to link an item with a transaction. It must be sent after the corresponding transaction hit.
await visitor.SendHit(new Item("#12345", "product", "sku123")
{
Price = 199.99,
Quantity = 1,
Category = "test"
});
- Constructor
Params | Type | Description |
---|---|---|
transactionId | string | Unique identifier for your transaction. |
name | string | Name of your item. |
code | string | Specifies the SKU or item code. |
- A hit of type
Item
has this following structure:
Property | Type | Description |
---|---|---|
TransactionId | string | Unique identifier for your transaction. |
Name | string | Name of your item. |
Code | string | Specifies the SKU or item code. |
Category | string | Specifies the category that the item belongs to. |
Price | double | Specifies the price for a single item/unit. |
Quantity | int | Specifies the number of items purchased. |
Event
This hit can be used for any event (e.g. Add To Cart click, newsletter subscription).
await visitor.SendHit(new Event(EventCategory.ACTION_TRACKING, "click")
{
Label = "label",
Value = 100,
});
- Constructor
Params | Type | Description |
---|---|---|
Category | Flagship.Hit.EventCategory | Specifies the category of your event. |
Action | string | Event name that will also serve as the KPI that you will have inside your reporting. Learn more |
- A hit of type
Event
has this following structure:
Property | Type | Description |
---|---|---|
Category | Flagship.Hit.EventCategory | Specifies the category of your event. |
Action | string | Event name that will also serve as the KPI that you will have inside your reporting. Learn more |
Label | string | Additional description of your event. |
Value | uint | (optional) Can be used to evaluate user interactions with individual site objects or content items. NOTE: this value must be non-negative. |
Managing visitor cache
The aims of the cache management is the response to the following problematic:
- Re-allocation in bucketing mode :
In bucketing mode, the SDK will always keep visitor in variation where he was allocated first, in case of the customer or the dynamic allocation has changed the traffic allocation. Indeed in bucketing mode the assignation is made on local device so changing campaign allocation in the platform would make the visitors see different campaigns.
- Handle offline mode on client side :
With the cache enabled, the SDK will try to retrieve the latest visitor data (campaign assignations) from the cache, also will save all the failed hits and UserExposed in order to resend them later.
To use the cache manager the intefaces IVisitorCacheImplementation
and IHitCacheImplementation
must be implemented through visitorCacheImplementation and hitCacheImplementation properties of configuration.
Visitor Cache
The visitor cache is used to store the visitor data in a database through the Flagship.Cache.IVisitorCacheImplementation
interface.
interface IVisitorCacheImplementation
{
TimeSpan? LookupTimeout { get; set; }
Task CacheVisitor(string visitorId, JObject data);
Task<JObject> LookupVisitor(string visitorId);
Task FlushVisitor(string visitorId);
}
CacheVisitor
function
CacheVisitor
functionThis method is called when the SDK needs to cache visitor information in your database.
Task CacheVisitor(string visitorId, JObject data)
It has 2 arguments :
Argument | Type | Description |
---|---|---|
visitorId | string | visitor ID |
Data | Newtonsoft.Json.Linq.JObject | visitor data. The JSON object has the follows shape see . |
LookupVisitor
function
LookupVisitor
functionThis method is called when the SDK needs to get the visitor information corresponding to visitor ID from your database.
It has to return an JSON object which follows this shape see.
Task<JObject> LookupVisitor(string visitorId)
It has one argument :
Argument | Type | Description |
---|---|---|
visitorId | string | visitor ID |
FlushVisitor
function
FlushVisitor
functionThis method is called when the SDK needs to erase the visitor information corresponding to visitor ID in your database.
It will be called every time setConsent
get false.
Task FlushVisitor(string visitorId)
It has one argument :
Argument | Type | Description |
---|---|---|
visitorId | string | visitor ID |
FlushVisitor
method will be called every timeSetConsent
get false.
Visitor Cache format
{
"Version": 1,
"Data": {
"VisitorId": "visitor_1",
"AnonymousId": null,
"Consent": true,
"Context": {
"qa_getflag": true,
"fs_client": ".NET",
"fs_version": "V3"
},
"AssignmentsHistory": {
"xxxxxxxxxxxxxxxxxxxx": "xxxxxxxxxxxxxxxxxxxx",
"yyyyyyyyyyyyyyyyyyyy": "yyyyyyyyyyyyyyyyyyyy"
},
"Campaigns": [
{
"CampaignId": "xxxxxxxxxxxxxxxxxxxx",
"VariationGroupId": "xxxxxxxxxxxxxxxxxxxx",
"VariationId": "xxxxxxxxxxxxxxxxxxxx",
"IsReference": false,
"Type": 2,
"Activated": false,
"Slug": xxxxxxxxxxxxxxx,
"Flags": {
"key": "value"
}
},
{
"CampaignId": "xxxxxxxxxxxxxxxxxxxx",
"VariationGroupId": "xxxxxxxxxxxxxxxxxxxx",
"VariationId": "xxxxxxxxxxxxxxxxxxxx",
"IsReference": false,
"Type": "",
"Activated": false,
"Slug": xxxxxxxxxxxxxxx,
"Flags": {
"myAwesomeFeature": 20
}
}
]
}
}
Hit Cache
The hit cache is used to store the failed hits and UserExposed in your database through the Flagship.Cache.IHitCacheImplementation
interface to handle it.
interface IHitCacheImplementation
{
TimeSpan? LookupTimeout { get; set; }
Task CacheHit(string visitorId, JObject data);
Task<JArray> LookupHits(string visitorId);
Task FlushHits(string visitorId);
}
CacheHit
function
CacheHit
functionThis method will be called to cache visitor hits when a hit has failed to be sent if there is no internet, there has been a timeout or if the request responded with something > 2XX.
Task CacheHit(string visitorId, JObject data)
It has 2 arguments :
Argument | Type | Description |
---|---|---|
visitorId | string | visitor ID |
data | Newtonsoft.Json.Linq.JObject | hit data. The JSON object has the follows shape see . |
LookupHits
function
LookupHits
functionThis method will be called to load hits corresponding to visitor ID from your database and will try to send them again in the background.
It has to return an JSON array which follows this shape see.
Task<JArray> LookupHits(string visitorId)
It has one argument :
Argument | Type | Description |
---|---|---|
visitorId | string | visitor ID |
FlushHits
function
FlushHits
functionThis method will be called to erase the visitor hits cache corresponding to visitor ID from your database.
NOTE: It will be called every time SetConsent
get false.
Task FlushHits(string visitorId)
It has one argument :
Argument | Type | Description |
---|---|---|
visitorId | string | visitor ID |
Hit Cache format
[
{
"Version": 1,
"Data": {
"VisitorId": "visitor_1",
"AnonymousId": null,
"Type": 4,
"Time": "2022-03-21T13:51:48.4696354+01:00",
"Content": {
"Category": 1,
"Action": "Event 2",
"Label": null,
"Value": null,
"VisitorId": "visitor_1",
"Type": 4,
"DS": "APP",
"AnonymousId": null,
"UserIp": null,
"ScreenResolution": null,
"Locale": null,
"SessionNumber": null
}
}
]
FlushHits
method will be called every timeSetConsent
get false.- After
LookupHits
has returned the visitor hits information corresponding to visitor ID, this data must be deleted from persistent storage.Hits
older than 4H will be ignored during the resending process.
API reference
Fs
class
Fs
classVisitor
class
Visitor
class- UpdateContext
- Context
- ClearContext
- FetchFlags
- GetFlag
- SetConsent
- HasConsented
- Authenticate
- Unauthenticate
- SendHit
Flag
class
Flag
classAppendix
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 customer.
You can overwrite these keys at any time. The keys-value pairs will be sent to the server in the user context and can be edited in the Persona section of the Flagship platform.
Note: All predefined contexts can be found as static property in Flagship.Enums.PredefinedContext
class
SDK constant Name | Description | Context variable name | Type | Auto-set by SDK | Example |
---|---|---|---|---|---|
DEVICE_LOCALE | Language of the device | sdk_deviceLanguage | String | No | fra |
DEVICE_TYPE | Type of the device | sdk_deviceType | DeviceType | No | Mobile |
DEVICE_MODEL | Model of the device | sdk_deviceModel | String | No | samsung E1200 |
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 | ubuntu / centos |
OS_VERSION_NAME | Version name of the OS | sdk_osVersionName | String | No | 9.0.0 |
OS_VERSION_CODE | Version code of the OS | sdk_osVersionCode | Number | No | 24 |
CARRIER_NAME | Name of the carrier or mobile virtual network operator | sdk_carrierName | String | No | free |
INTERNET_CONNECTION | What is the internet connection | sdk_internetConnection | String | No | 5g |
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 | No | 40 |
INTERFACE_NAME | Name of the interface | sdk_interfaceName | String | No | ProductPage |
FLAGSHIP_CLIENT | Flagship SDK client (Reserved) | fs_client | String | Yes | TS |
FLAGSHIP_VERSION | Version of the Flagship SDK (Reserved) | fs_version | String | Yes | 2.0.0 |
FLAGSHIP_VISITOR | Current visitor id (Reserved) | fs_users | String | Yes | visitor_id |
To overwrite the keys, use the
updateContext
method
Updated about 1 month ago