.NET V1.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 modifications
- 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
- Your server/device must have an access to the internet.
Good to know
- Github repository: https://github.com/flagship-io/flagship-dotnet-sdk
- Open source demo app: https://github.com/flagship-io/flagship-dotnet-sdk/tree/main/Flagship.QAApp
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
Environment ID
You can find your environment id in the parameters\integration section of your Flagship account. (Check Getting Started)
// Use the Flagship package
using Flagship;
// ...
// Using the Decision API (default)
var client = FlagshipBuilder.Start(
"ENV_ID",
"API_KEY"
);
// Using the Bucketing mode
var builder = new FlagshipOptions.Builder()
.WithDecisionMode(Mode.Bucketing)
.WithBucketingOptions(System.TimeSpan.FromMilliseconds(newEnv.PollingInterval));
var client = FlagshipBuilder.Start(
"ENV_ID",
"API_KEY",
new FlagshipOptions.Builder()
.WithDecisionMode(Mode.Bucketing).Build()
);
To initialize and start the library, just call the Start function of the Flagship package,
using the bucketing function builder if you want to use the bucketing mode
The start function return a Flagship client instance for your environment.
Parameter | Type | Description |
---|---|---|
envId | string | Environment id provided by Flagship. |
apiKey | string | Api authentication key provided by Flagship. |
options | FlagshipOptions | Option to customize the SDK behavior |
You can find your
apiKey
and yourenvironmentId
on your Flagship account, in Parameters > Environment & Security. Find this ID
Decision Mode
API
Mode
When the SDK is running in API
mode, the campaign assignments and targeting validation take place server-side.
In this mode, each call to the SynchronizeModifications
method from the visitor instance to refresh the modifications will create an HTTP request.
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.
It is possible to configure the interval of polling refresh with the PollingInterval configuration builder. Learn more
Options
You can customize the SDK behavior using the FlagshipOptions
class.
The FlagshipOptions
class can be created with the FlagshipOptions.Builder
class:
var builder = new FlagshipOptions.Builder()
The FlagshipOptions.Builder
object has the following methods:
Builder WithDecisionMode(Mode mode)
Start Flagship SDK in the selection mode (API is the default).
Parameter | Type | Description |
---|---|---|
Mode | Mode (enum) | Decision mode to select for the SDK |
Builder WithAPIOptions(TimeSpan timeout)
Customize the options for the API decision mode.
Right now, the only option is the timeout.
If the Decision API call times out after the specified timeout, then default modification values will be returned when calling GetModifications.
Parameter | Type | Description |
---|---|---|
timeout | TimeSpan | The Decision API call timeout |
Builder WithBucketingOptions(TimeSpan? pollingInterval = null)
WithBucketingOptions method enables you to customize the bucketing engine.
For now, the only available option is the the polling interval, to determine how often
the bucketing engine will poll the Flagship CDN for the newest configuration.
Parameter | Type | Description |
---|---|---|
pollingInterval | TimeSpan? | Bucketing polling interval (default to 1 minute). |
Create a visitor
The SDK provides a method create a new visitor with an ID and a context.
The visitor context is a property dataset which defines the current user of your app. This dataset is sent and used
by the Flagship decision API as targeting for campaign allocation. For example, you could pass a VIP status in the context and then the decision API would enable or disable a specific feature flag.
Visitor context values are used to match a visitor to the targeting of a campaign
Visitor context values type must be:
- string
- number (int, float or double)
- bool
// Create visitor context
var context = new Dictionary<string, object>();
context.Add("key", "value");
// Create a visitor
var visitor = client.NewVisitor("visitor_id", context);
The NewVisitor function takes the following parameters:
Parameter | Type | Description |
---|---|---|
visitorID | string | The ID of the visitor (must be unique for a visitor) |
context | map[string]interface{} | The context of the visitor. It should match those defined in your campaigns to target your users on it. |
Updating the visitor Context
The visitor context can be updated in case some context linked to your visitor has changed.
The SDK provides 2 methods to change the visitor context:
- Either change a single key of the context
- Or replace the whole context with a new one
// Update a single key
visitor.UpdateContext("vipUser", true);
visitor.UpdateContext("age", 30);
// Update the whole context
var newContext = new Dictionary<string, object>();
newContext.Add("vipUser", true);
newContext.Add("age", 30);
visitor.UpdateContext(newContext);
void UpdateContext(string key, object value)
This functions update the visitor context value matching the given key.
A new context value associated with this key will be created if there is no previous matching value.
Parameter | Type | Description |
---|---|---|
key | string | key to associate with the following value |
value | object | new context value |
void UpdateContext(IDictionary<string, object> context);
Parameter | Type | Description |
---|---|---|
newContext | IDictionary<string, object> | new context dictionary |
Visitor context values type must be:
- string
- number (int, float or double)
- bool
Campaign synchronization
Synchronizing campaigns
Synchronizing campaign modifications allows you to automatically call the Flagship decision API (or bucketing engine), which makes the allocation according to user context and gets all their modifications.
All the applicable modifications are stored in the SDK and are updated synchronously when SynchronizeModifications()
is called.
This function has no parameters, and return an awaitable Task:
Task SynchronizeModifications();
Example of utilisation:
// In an async function
await visitor.SynchronizeModifications();
SynchronizeModifications must be called before trying to get a modification value
Getting modifications
Once the campaign has been assigned and synchronized all the modifications are stored in the SDK. Then, you can retrieve them with the following functions:
var discountName = visitor.GetModification("discountName", "Black Friday", true);
// If there is not error (and if there is, your value will still be set to defaut), you can use your modification value in your business logic
var discountValue = getDiscountFromDB(discountName);
GetModification
is a generic method that takes a modification key, a default value & a bool and returns the modification value.
T GetModification<T>(string key, T defaultValue = default, bool activate = true)
Parameter | Type | Required | Description |
---|---|---|---|
key | string | Yes | key associated to the modification. |
defaultValue | string, bool, int, float, double, Object | Yes | default value returned when the key doesn't match any modification value. |
activate | bool | 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. |
Getting campaign information
You may need to send campaign IDs to a third-party for reporting and/or analytics purposes. It is now possible to retrieve campaign IDs for a specific modification key.
var infos = visitor.GetModificationInfo("key");
ModificationInfo GetModificationInfo(string key)
Parameter | Type | Description |
---|---|---|
key | str | Key associated with the modification. |
It returns a struct containing CampaignId
, VariationGroupID
, VariationID
, IsReference
, or null
if the modification is not found (i.e. user does not belong to the campaign).
Activating modifications
Once a modification has been printed on the screen for a user, you must send an activation event to tell Flagship that the user has seen this specific modification.
// Activate the modification automatically when retrieving it
var color = visitor.GetModification("discountName", "Black Friday", true);
// ---OR---
// Activate the modification later on manually
visitor.ActivateModification("discountName")
Task ActivateModification(string key);
Parameter | Type | Description |
---|---|---|
key | string | key which identifies the modification |
Hit Tracking
This section helps send tracking and learn how to build hits in order to aprove campaign goals.
The different types of Hits are:
They must all be built and sent with the following function:
Task SendHit<T>(T hit) where T : BaseHit;
Common parameters
These parameters can be sent with any type of hit. They are part of the BaseHit
class that all Hit types implements
Parameter | Type | Description |
---|---|---|
UserIP | string | optional User IP |
ScreenResolution | string | optional Screen Resolution. |
UserLanguage | string | optional User Language |
CurrentSessionTimeStamp | string | optional Current Session Timestamp |
SessionNumber | int | optional Session Number |
Hit types
Page
await visitor.SendHit(new Page
{
DocumentLocation: "http://localhost:8080",
})
This hit should be sent each time a visitor arrives on a new interface.
Hit parameter | Type | Required | Description |
---|---|---|---|
DocumentLocation | string | Yes | URL of the page, must be a valid URL |
Screen
await visitor.SendHit(new Screen
{
DocumentLocation: "My interface name",
})
This hit should be sent each time a visitor arrives on a new interface.
Hit parameter | Type | Required | Description |
---|---|---|---|
DocumentLocation | string | Yes | Name of the interface |
Transaction
This hit should be sent when a user complete a Transaction.
await visitor.SendHit(new Transaction
{
Id = "tid",
Affiliation = "affiliation"
});
Hit Parameter | Type | Required | Description |
---|---|---|---|
TransactionId | string | Yes | Transaction unique identifier. |
Affiliation | string | Yes | Transaction name. Name of the goal in the reporting. |
Revenue | decimal? | No | Total revenue associated with the transaction. This value should include any shipping or tax costs. |
Shipping | decimal? | No | Specifies the total shipping cost of the transaction. |
ShippingMethod | string | No | Specifies the shipping method of the transaction. |
Tax | decimal? | No | Specifies the total taxes of the transaction. |
Currency | string | No | Specifies the currency used for all transaction currency values. Value should be a valid ISO 4217 currency code. |
PaymentMethod | string | No | Specifies the payment method for the transaction. |
ItemCount | int? | No | Specifies the number of items for the transaction. |
CouponCode | string | No | Specifies the coupon code used by the customer for the transaction. |
Item
This hit is linked to a transaction. It must be send after the corresponding transaction.
await visitor.SendHit(new Item
{
TransactionId = "tid",
Name = "product",
Code = "product-1"
});
class Item(transactionId: string, productName: string) : HitBuilder<Item>()
Hit Parameter | Type | Required | Description |
---|---|---|---|
TransactionId | string | Yes | Transaction unique identifier. |
Name | string | Yes | Product name. |
Price | double | No | Specifies the item price. |
Code | string | Yes | Specifies the item code or SKU. |
Category | string | No | Specifies the item category. |
Quantity | int | No | Specifies the item quantity |
Event
This hit can be anything you want: for example a click or a newsletter subscription.
await visitor.SendHit(new Event
{
Category = EventCategory.ActionTracking,
Action = "bookedEvent",
Value = 1
});
Hit Parameter | Type | Required | Description |
---|---|---|---|
Category | EventCategory | Yes | category of the event ("Action Tracking" or "User Engagement"). |
Action | string | Yes | the event action. |
Label | string | No | label of the event. |
Value | int | No | Specifies a value for this event. must be non-negative. |
Release notes
1.0.0
Added
- Basic flow
- Decision modes API & Bucketing
- OptionBuilder
Updated over 1 year ago