# .NET v3.3.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](mailto:product.feedback@abtasty.com?subject=Flagship%20Developer%20Documentation) if you have any questions regarding this documentation. #### SDK features That SDK version helps you : * Set a [visitor ID](doc:glossary#visitor-id) * Update [visitor context](doc:glossary#user-context) * Assign campaigns via the [Decision API](doc:decision-api#campaigns) or the [Bucketing](doc:bucketing) * Get flags * Activate campaigns * Send hits to our [Universal Collect](doc:universal-collect-documentation) #### Prerequisites * This SDK requires **.Net** with the following target framework versions: * net40 * net45 * netstandard2.0 * net5.0 or later [Lern more](https://www.nuget.org/packages/Flagship.SDK#supportedframeworks-body-tab) * Your server/device must have an access to the internet. #### Good to know * Github repository: <[https://github.com/flagship-io/flagship-dotnet-sdk>](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 ```shell 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. ```csharp // Use the Flagship package using Flagship.Main; // ... Fs.Start("ENV_ID", "API_KEY"); ``` **`Start` static function** This method starts 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) | #### 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 : ```csharp // 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), }); ``` ```csharp // 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` | `Object` |

Required
Specify a custom implementation of LogManager to receive logs from the SDK.
Note: The object must implement the IFsLogManager interface.

| | 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 implements the IVisitorCacheImplementation interface to handle the visitor cache. see cache-manager

| | HitCacheImplementation | `Flagship.Cache.IHitCacheImplementation` | undefined |

Optional
Define an object that implements the IHitCacheImplementation interface to handle the visitor cache. see cache-manager

| | DisableCache | boolean | false |

Required
If set to true, hit cache and visitor cache will be disabled; otherwise, they will be enabled. see cache-manager

| | StatusChanged | `Flagship.Delegate.StatusChangeDelegate` | undefined |

Optional
Define an event to get a callback when the SDK status changes.
see arguments.

| | TrackingMangerConfig | Flagship.Config.ITrackingManagerConfig | `Object` |

Define options to configure hit batching.
trackingMangerConfig

| | OnVisitorExposed | `Flagship.Delegate.OnVisitorExposedDelegate` | undefined |

Optional
Define an event to get a callback each time a Flag has been exposed to a visitor (when a flag has been seen by your visitor) and succeeded.
see arguments

| | DisableDeveloperUsageTracking | boolean | false |

The SDK will collect usage data to help us improve our product.

If set to true, no usage data will be collected.

| \\ **Decision Mode** **`API` Mode** (by default) When the SDK operates in `API` mode, it uses our [Decision API](doc:decision-mode) to manage campaign assignments and validate targeting. In this mode, each time a new Decision is needed, the SDK sends an HTTPS request to the API. This mode is enabled by default for all our SDKs. **`Bucketing` Mode** In `Bucketing` mode, the SDK downloads all campaign configurations in a single bucketing file. This allows the SDK to compute variation assignments on the client-side. The bucketing file is cached and only re-downloaded when campaign configurations are updated in the Flagship interface. [**Learn more**](doc:bucketing) \\ **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. ```csharp 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. [see`FlagshipStatus`](#flagshipstatus) | \\ **OnVisitorExposed** In some cases, you'll need to send information about the exposure (When a flag has been seen by your visitor), like sending visitor and flag data to third parties. To centralize it, we provide the `OnVisitorExposed` event in the configuration option of the SDK. The `OnVisitorExposedDelegate` delegate has 2 arguments with the following shape: | Parameter | Type | Description | | -------------- | --------------- | ----------------------------------------------------------------------------------- | | exposedVisitor | IExposedVisitor | An interface to get information about the visitor to whom the flag has been exposed | | exposedFlag | IExposedFlag | An interface to get information about the flag that has been exposed. | ```csharp using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; namespace Flagship.FsVisitor { public interface IExposedVisitor { /// /// The key of flag /// string Id { get; } /// /// Visitor anonymous id /// string AnonymousId { get; } /// /// Visitor context /// IDictionary Context { get; } } } ``` ```csharp using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; namespace Flagship.FsFlag { public interface IExposedFlag { /// /// Get the flag key /// string Key { get; } /// /// Get the flag value /// object Value { get; } /// /// Get the flag default value /// object DefaultValue { get; } /// /// Get the flag metadata /// IFlagMetadata Metadata { get; } } } ``` Here is an example on how to use this callback: [Example with Mixpanel integration](https://docs.developers.flagship.io/docs/integrate-with-mixpanel)\ [Example with Segment integration](https://docs.developers.flagship.io/docs/integrate-with-segmentcom) \\ **trackingMangerConfig** The SDK features a batching system for sending hits, which can be configured using three options: `CacheStrategy`, `PoolMaxSize`, and `BatchIntervals`. Using the TrackingManager’s batch processing reduces network traffic, prevents hit loss through caching, and resends any failed hits. Hits are first added to an internal pool as they are emitted by visitors. The pool is then emptied by batching all hits and sending them when either the PoolMaxSize is reached or the BatchIntervals timer is triggered. If a batch fails, all hits within it are returned to the pool for future iteration and the cache is updated based on the selected cache strategy. **Note:** At any time, when your app is about to **terminate** or **crash**, you should call [`Flagship.close()`](#close-function) to batch and send all hits that are in the pool. | Key | Type | Default value | Description | | -------------- | ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CacheStrategy | Flagship.Enums.CacheStrategy | `PERIODIC_CACHING` |

Define the strategy that will be used for hit caching
see cacheStrategy

| | PoolMaxSize | number | `100` |

Define the minimum number of hits the pool must reach to automatically batch all hits in the pool and send it.

Note:
- Must be greater than 5 otherwise default value will be used
- Having a large PoolMaxSize can lead to performance issues

| | BatchIntervals | TimeSpan | `10s` |

Define a regular interval in seconds to trigger batch processing

Note:
- The process will batch all hits from the pool whether PoolMaxSize is reached or not
- Must be between 1sec and 14400s (4hours). Otherwise default value will be applied

| \\ **CacheStrategy** `Flagship.Enums.CacheStrategy` is an enum defining the different caching strategies | Key | Type | value | Description | | ------------------- | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CONTINUOUS\_CACHING | number | 0 |

When a hit is emitted, it will first be cached in database using IHitCacheImplementation and added into the pool, then after batching and sending, it will also be flushed from database using IHitCacheImplementation.

Note: recommended for client side applications

| | PERIODIC\_CACHING | number | 1 |

When a hit is emitted, it will be added into the pool, then after batching and sending, all database hits will be flushed, then the entire pool will be cached using IHitCacheImplementation for both actions.

Note: recommended for server-side applications

| ```csharp // Use the Flagship package using Flagship.Main; // ... Fs.Start("ENV_ID", "API_KEY", new DecisionApiConfig { TrackingMangerConfig = new TrackingManagerConfig { CacheStrategy = Flagship.Enums.CacheStrategy.CONTINUOUS_CACHING, PoolMaxSize = 100, BatchIntervals = TimeSpan.FromSeconds(10) } }); ``` > πŸ“˜ > > * The `CONTINUOUS_CACHING strategy` (`recommended for client side apps`) should be used when your application is running in an environment where the probability of data loss is high. > > Keep in mind that this strategy can do a lot of database I/O depending on how many hits your visitor can send. > > * The `PERIODIC_CACHING strategy` (`recommended for server side apps`) should be used when your application sends a lot of hits and the probability of data loss is low. > > In this strategy, the number of I/Os in the database is low. \ \\ #### Other `Flagship.Main.Fs` class methods **`Status` property** Return current status of Flagship SDK. [see`FlagshipStatus`](#flagshipstatus) * `public static FlagshipStatus Status` **`Config` property** Return the current config used by the SDK. [see configuration attribute](#advanced-configuration) * `public static FlagshipConfig Config` **`Visitor` property** Return the last visitor created and saved or return undefined if no visitor has been saved. [see newVisitor](#newvisitor-function). * `public static Visitor Visitor` \\ **`Close` function** Most of the time you don't need to manually close the SDK, but when your application is about to `terminate`, you should call the `Close` method of the `Fs`class to avoid data loss. When called, it will batch and send all hits that are in the pool before the application is closed * **`public static async Task Close()`** \ \\ ### Create a visitor The [`Flagship.FsVisitor.Visitor`](#visitor-class) 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](https://github.com/flagship-io/Gitbook/blob/main/docs/experience-continuity/README.md)) 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](#getting-flags) method. **Let's take an example:**\ if you want to enable a specific feature to all your `VIPs` visitor,\ 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`. ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["isVIP"] = true, ["country"] = "NL", ["loginProvider"] = "Google" }) .Build(); ``` **`NewVisitor` static function** Creates 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 context)` Specify Visitor initial context key / values used for targeting. | Parameter | Type | Description | | ----------- | ------------------------------ | ------------------------ | | withContext | IDictionary\\| | visitor initial context. | > 🚧 > > * Visitor context keys must have a type of `string` > * Visitor context values must have a type of `string`, `bool`, `numeric` > * Visitor 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 visitor context is a property dataset that defines the current visitor 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. ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["isVIP"] = true, ["country"] = "NL", ["loginProvider"] = "Google" }) .Build(); visitor.UpdateContext("lastPurchaseDate", DateTime.Now.ToShortDateString()); ``` **`updateContext` function** Update 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 context)` It has one argument : | Argument | Type | Description | | -------- | ---------------------------- | ---------------------- | | context | IDictionary\ | 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** This property returns all the visitor's current context as an object * \`IDictionary\ Context **`ClearContext` function** Clear the actual visitor context * `void ClearContext()` > 🚧 > > * Visitor context keys must have a type of `string` > * Visitor context values must have a type of `string`, `bool`, `numeric` > * Visitor context keys and values are **case sensitive** #### update context with predefined keys of context ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["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**](#predefined-user-context-keys-) about predefined keys of context ### Managing visitor campaigns #### Fetching Flags The `FetchFlags()` method of the [`Visitor`](#visitor-class) instance, according to [**Decision Mode**](#decision-mode), will either automatically call the Flagship Decision API to run campaign assignments according to the current visitor 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. ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["isVIP"] = true, ["country"] = "NL", ["loginProvider"] = "Google" }) .Build(); await visitor.FetchFlags(); //ready to use all features from the SDK ``` **`FetchFlags` function** In DecisionApi Mode this function calls the Flagship Decision API to run campaign assignments according to the current visitor 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: ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["isVIP"] = true, ["country"] = "NL", ["loginProvider"] = "Google" }) .Build(); await visitor.FetchFlags(); var flag = visitor.GetFlag("displayVipFeature", false); ``` **`GetFlag` function** Return a [Flag](#flag-class) 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 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** To retrieve [flag](#flag-class) current value, simply call GetValue() method of the Flag object. ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["isVIP"] = true, ["country"] = "NL", ["loginProvider"] = "Google" }) .Build(); await visitor.FetchFlags(); var flag = visitor.GetFlag("displayVipFeature", false); var flagValue = flag.GetValue(); ``` * `T GetValue([bool visitorExposed=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 | | -------------- | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | visitorExposed | Boolean | true |

Tells Flagship the visitor 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 VisitorExposed() afterward when the visitor sees it.

| #### Getting flags campaigns metadata **`Metadata` property** You 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. ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["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. ```csharp interface IFlagMetadata { string CampaignId { get; } string VariationGroupId { get; } string VariationId { get; } bool IsReference { get; } string CampaignType { get; } string Slug { get; } string ToJson(); } ``` | Key\Property | Type | Description | | ---------------- | -------- | ---------------------------------------- | | CampaignId | string | ID of the campaign | | VariationGroupId | string | | | VariationId | string | The variation ID assigned to the visitor | | IsReference | boolean | Specify if its the reference variation | | CampaignType | string | campaign type | | Slug | string | campaign slug | | ToJson | function | Return a Json of current metadata | #### Report a Flag exposure **`VisitorExposed` function** By default when the method GetValue() is called, The SDK considers that the visitor have seen the effect of your Flag, unless you pass false to GetValue(). In this case you will have to call VisitorExposed(). There are two ways for exposing a visitor to a flag: 1. Pass an `visitorExposed=true` parameter to the **GetValue()** method. 2. Use the following **VisitorExposed()** method from the Flag instance. ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["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 exposure await flag.VisitorExposed(); ``` * `Task VisitorExposed()` Tells Flagship the visitor have been exposed and have seen this flag. This will increment the visits for the current variation on your campaign reporting. No visitor exposure 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** This method will return true if a Flag exists in Flagship * `bool Exists { get; }` ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) .WithContext(new Dictionary { ["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 : 1. Set `HasConsented` to true when creating a new visitor 2. Use `SetConsent` method of visitor instance ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor("") .IsAuthenticated(true) .HasConsented(true) // set hasConsented to true .WithContext(new Dictionary { ["isVIP"] = true, ["country"] = "NL", ["loginProvider"] = "Google" }) .Build(); // or use setConsent method visitor.SetConsent(true); ``` **`SetConsent` function** Set 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** Return True if the visitor has consented for private data usage, otherwise return False. * `bool HasConsented { get; }` ### Experience Continuity Dealing with anonymous and logged-in visitors, 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: 1. Set IsAuthenticated to true when creating a new visitor 2. 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. ```csharp using Flagship.Main; //... var visitor = Fs.NewVisitor() .WithContext(new Dictionary { ["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. ```csharp // 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: ```csharp 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 visitors 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](doc:universal-collect-documentation). There are five different types of Hits available: | Class | Description | | ----------- | ----------------------------------- | | Page | Visitor has seen a URL. | | Screen | Visitor has seen a screen. | | Transaction | Visitor has made a transaction. | | Item | Item bought in a transaction. | | Event | Visitor has made a specific action. | **They must all be built and sent with the following function from the `Visitor` instance:** ```csharp await visitor.SendHit(new Screen("abtastylab")); ``` **`sendHit` function** Send Hit to Flagship servers for reporting. * `Task SendHit(HitAbstract hit)` | Parameter | Type | Default | Description | | --------- | ----------- | -------- | ----------------------------- | | hit | HitAbstract | required | Hit to send. [see Hit](#page) | #### Hit common optional parameters ```csharp await visitor.SendHit(new Screen("abtastylab") { UserIp = "127.0.0.1", ScreenResolution= "800X600", Locale = "fr", SessionNumber = "1234" }); ``` | Parameter | Type | Description | | ---------------- | ------ | ----------------------------- | | UserIp | string | (Optional) visitor IP | | ScreenResolution | string | (Optional) Screen resolution. | | Locale | string | (Optional) visitor language | | SessionNumber | string | (Optional) Session number | #### Page This hit should be sent each time a visitor arrives on a new page. ```csharp 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. ```csharp 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 visitor complete a Transaction. ```csharp 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**](https://github.com/flagship-io/Gitbook/blob/main/docs/glossary/README.md#kpi) | * 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**](https://github.com/flagship-io/Gitbook/blob/main/docs/glossary/README.md#kpi) | | 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. ```csharp 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). ```csharp 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**](https://github.com/flagship-io/Gitbook/blob/main/docs/glossary/README.md#kpi) | * 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**](https://github.com/flagship-io/Gitbook/blob/main/docs/glossary/README.md#kpi) | | Label | string | Additional description of your event. | | Value | uint |

(optional) Can be used to evaluate visitor 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 VisitorExposed 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](#advanced-configuration). #### Visitor Cache The visitor cache is used to store the visitor data in a database through the `Flagship.Cache.IVisitorCacheImplementation` interface. ```csharp interface IVisitorCacheImplementation { TimeSpan? LookupTimeout { get; set; } Task CacheVisitor(string visitorId, JObject data); Task LookupVisitor(string visitorId); Task FlushVisitor(string visitorId); } ``` **`CacheVisitor` function** This 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`](#visitor-cache-format). | **`LookupVisitor` function** This 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](#visitor-cache-format). * `Task LookupVisitor(string visitorId)` It has one argument : | Argument | Type | Description | | --------- | ------ | ----------- | | visitorId | string | visitor ID | **`FlushVisitor` function** This 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`](#setconsent-function) get false. * `Task FlushVisitor(string visitorId)` It has one argument : | Argument | Type | Description | | --------- | ------ | ----------- | | visitorId | string | visitor ID | > πŸ“˜ > > * `FlushVisitor` method will be called every time [`SetConsent`](#setconsent-function) get false. **Visitor Cache format** ```json { "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 hits in your database depending on strategy used through the `IHitCacheImplementation` interface which defines the methods that an object must implement to handle it. ```csharp interface IHitCacheImplementation { TimeSpan? LookupTimeout { get; set; } Task CacheHit(JObject data); Task LookupHits(); Task FlushHits(string[] hitKeys); Task FlushAllHits(); } ``` **`CacheHit` function** This method will be called to cache hits depending on cache strategy used. * `Task CacheHit(JObject data)` It has 2 arguments : | Argument | Type | Description | | -------- | ---------------------------- | --------------------------------------------------------------------------- | | data | Newtonsoft.Json.Linq.JObject | hit data. The JSON object has the follows shape [`see`](#hit-cache-format). | **`LookupHits` function** This method will be called to load all hits from your database and trying to send them again in the background. It has to return an JSON object which follows this shape [see](#hit-cache-format). * `Task LookupHits()` \\ **`FlushHits` function** his method will be called to erase all hits matching the unique Hits ID from your database. **NOTE:** It will be called every time [`SetConsent`](#setconsent-function) get false to erase all hits from database for visitor who set consent to false. * `Task FlushHits(string[] hitKeys)` It has one argument : | Argument | Type | Description | | -------- | --------- | -------------- | | hitKeys | string\[] | Unique hit IDS | \\ **`FlushAllHits` function** This method will be called to erase all hits in your database without exception. * `Task FlushAllHits()` \\ **Hit Cache format** ```json { "visitorId:Guid": { "version": 1, "data": { "visitorId": "visitorId", "anonymousId": "d7c40c75-1833-4137-a3d0-8a9837e36e79", "type": 1, "time": "2023-04-06T11:03:51.1885042-05:00", "content": { "documentLocation": "Screen 1", "key": "visitorId:Guid", "visitorId": "visitorId", "type": 1, "ds": "APP", "anonymousId": "d7c40c75-1833-4137-a3d0-8a9837e36e79", "userIp": null, "screenResolution": null, "locale": null, "sessionNumber": null, "createdAt": "2023-04-06T11:03:51.1864852-05:00" } } } } ``` > πŸ“˜ > > * `FlushHits` method will be called every time [`setConsent`](#setconsent-function) get false. > * `Hits` older than 4H will be ignored during the resending process. \\ ### API reference #### `Fs` class * [Start](#start-static-function) * [NewVisitor](#newvisitor-static-function) * [Close](#close) * [Status](#status-property) * [Config](#config-property) * [Visitor](#visitor-property) #### `Visitor` class * [UpdateContext](#updatecontext-function) * [Context](#context-property) * [ClearContext](#clearcontext-function) * [FetchFlags](#fetching-flags) * [GetFlag](#getflag-function) * [SetConsent](#setconsent-function) * [HasConsented](#hasconsented-property) * [Authenticate](#authenticate) * [Unauthenticate](#unauthenticate) * [SendHit](#sendhit-function) #### `Flag` class * [GetValue](#getvalue-function) * [Metadata](#metadata-property) * [VisitorExposed](#userexposed-function) * [Exists](#exists-property) ### Appendix #### Predefined visitor context keys : The Flagship SDK contains predefined visitor 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 visitor context and can be edited in the [Persona](https://github.com/flagship-io/Gitbook/blob/main/docs/glossary/README.md#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`](#update-context-with-predefined-keys-of-context) method --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.abtasty.com/server-side/sdks/net/archived-versions/archived-net-v3-3-x.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.