Reference
FlagshipProvider
FlagshipProvider
Here is the full list of props available to use in the FlagshipProvider
React component:
Attribute | Type | Default | Description |
---|---|---|---|
envId | string | Required | Environment id provided by Flagship. |
apiKey | string | Required | Api authentication key provided by Flagship. |
decisionMode | DECISION-API |BUCKETING |BUCKETING_EDGE | DECISION-API | The SDK running mode. see Decision Mode |
fetchNow | boolean | true | Determines whether to automatically fetch flags data when creating a new Visitor . |
visitorData | object | Required | This is the data to identify the current visitor using your app. See arguments |
reuseVisitorIds | boolean | true | client-side only If true, the SDK will save the visitor ID and/or anonymous ID and reuse it for the next session if visitorId is not set, to maintain cross-session visitor experience. |
loadingComponent | ReactNode | undefined | This component will be rendered when Flagship is loading at first initialization only. By default, the value is undefined. It means it will display your app and it might display default modifications value for a very short moment. |
shouldSaveInstance | boolean | true | If true, the newly created visitor instance will be returned and saved into Flagship. Otherwise, the newly created visitor instance won't be saved and will simply be returned. |
initialCampaigns | object | undefined | Optional An object containing the data received when fetching the Flagship decision API (decisionMode="API"). Providing this property avoids the SDK from having an empty cache during first initialization. |
initialFlagsData | array | undefined | Optional A set of flag data provided to avoid the SDK from having an empty cache during the first initialization. |
onFetchFlagsStatusChanged | function(object):void | undefined | Optional Callback function that will be called when the fetch flags status changes. see arguments |
timeout | number | 2 | The timeout in seconds for API requests. Note: timeout can't be lower than 0 second. |
logLevel | number | 9 | The maximum log level to display. seeLogLevel |
logManager | object | Defined | A custom implementation of the LogManager interface to receive logs from the SDK. Note: The object must fill Interface IFlagshipLogManager |
decisionApiUrl | string | https://decision.flagship.io/v2 | This setting can be useful if you need to simulate the API for tests such as end-to-end or if you want to move to an earlier version of the Flagship API. |
pollingInterval | number | 5 | Bucketing mode only The delay in seconds between two bucketing polling requests. Note:If 0 is given, it will only poll once at start time. |
hitDeduplicationTime | number | 2.5 | The delay in seconds for hit deduplication. After a hit is sent, any future attempts to send the same hit will be blocked until the specified delay has expired. Note: If the value is 0, no deduplication process will be used. |
initialBucketing | object | undefined | Optional An object containing the data received when fetching the bucketing endpoint. Providing this object will make bucketing ready to use and the first polling will immediately check for updates. |
visitorCacheImplementation | object | Defined | Optional An object that implements the visitorCacheImplementation interface to handle the visitor cache. see cache management |
hitCacheImplementation | object | Defined | Optional An object that implements the IHitCacheImplementation , interface to manage hits cache. see cache management |
disableCache | boolean | false | If set to true, hit cache and visitor cache will be disabled; otherwise, they will be enabled.. see cache management |
onSdkStatusChanged | function(number):void | undefined | Optional A callback function to be called when the SDK status has changed. see arguments. |
onBucketingSuccess | function(object):void | undefined | Optional A callback function to be called when the first bucketing polling succeeds. see arguments |
onBucketingFail | function(error):void | undefined | Optional A callback function to be called when the first bucketing polling fails. see arguments |
onBucketingUpdated | function(object):void | undefined | Optional A callback function to be called each time bucketing data from Flagship has been updated. see arguments |
onLog | function(level: LogLevel, tag: string, message: string):void | undefined | Optional A callback function to be called whenever the SDK needs to report a log. see arguments |
trackingManagerConfig | object | defined | Options to configure hit batching. trackingManagerConfig |
onVisitorExposed | function(object):void | undefined | Optional A callback function to be called each time a flag is exposed to a visitor (i.e., when an activation hit is sent by the SDK). see arguments |
fetchThirdPartyData | boolean | false | Optional Bucketing mode only If true, the SDK will fetch the visitor's segment from the universal data connector each time fetchFlags is called and append those segments in the visitor context. |
nextFetchConfig | object | { revalidate: 20 } | Optional In Next.js 13, you can define the time in seconds for storing SDK route cache before revalidation. learn more |
fetchFlagsBufferingTime | number | 2 | Optional The delay in seconds for buffering fetch flags calls. After the SDK has fetched flags, they will be buffered for the specified delay. During this delay, any subsequent fetch flags calls will return the same flags. Note: - If a value of 0 is given, no buffering process will be used. - If visitor data has changed, the buffering will be bypassed. |
disableDeveloperUsageTracking | boolean | false | Determines whether to disable the collection of analytics data. |
fetchFlagsOnBucketingUpdated | boolean | false | Bucketing mode only If true, it'll automatically call fetchFlags when the bucketing file has updated. |
Information
- Any change to the
visitorData
prop will automatically fetch flags.- When the props
fetchNow
is set to true, the SDK will automatically fetch flags immediately after creating the visitor. see more- If the props
visitorData
is null, no visitor will be initialized until it is set- When both
initialCampaigns
andinitialFlags
are provided, the system will disregardinitialCampaigns
and only useinitialFlags
.- When the SDK is running in
Bucketing mode
(decisionMode="BUCKETING"), the polling interval will restart when any of the following props change after the first render:envId
,apiKey
,decisionMode
.
visitorData
The visitorData
prop includes the following keys
key | Type | Default | Description |
---|---|---|---|
id | string | undefined | Optional Unique visitor identifier. Note: - If not set, it will be generated automatically. - In client-side, if not specified, the id will either be automatically generated or will be the visitor id from the previous session (if reuseVisitorIds is set to true ). |
hasConsented | boolean | undefined | Required Specifies if the visitor has consented for personal data usage. When set to false, some features will be deactivated and the cache will be deactivated and cleared. |
context | object | {} | Optional The visitor context is a dataset key/value that defines the current visitor. It is sent to Flagship for targeting purposes (use-case assignment) and to enrich reporting with Context Filters. Note:Context keys must be strings, and the value types must be one of the following: number, boolean, or string. |
isAuthenticated | boolean | false | Optional Specify if the visitor is authenticated or anonymous for Experience continuity. |
Decision Mode
DECISION-API
Mode (by default)
When the SDK operates in API
mode, it uses our Decision API 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
DecisionMode
is an enum defining the decision type
Key | Value | Type | Description |
---|---|---|---|
DECISION_API | DECISION-API | string | Flagship SDK mode Decision API |
BUCKETING | BUCKETING | string | Flagship SDK mode bucketing |
onLog
The onLog
function has 3 arguments
Argument | Type | Description |
---|---|---|
level | number | Get the log level. see LogLevel |
tag | string | Get the function that triggered the log |
message | string | Get a description of the log |
import { LogLevel, FlagshipProvider } from "@flagship.io/react-sdk";
const App = () => (
<>
<FlagshipProvider
envId="YOUR_ENV_ID"
apiKey="YOUR_API_KEY"
visitorData={{
id: 'YOUR_VISITOR_ID',
hasConsented: true,
context: {
// some context
},
}}
onLog={(level, tag, message) => {
console.log(`[${LogLevel[level]}] [${tag}] : ${message}`)
}}
>
{/* [...] */}
</FlagshipProvider>
</>
)
LogLevel
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. |
IFlagshipLogManager
The aims of this Interface is to define methods that an object must have in order to receive Flagship SDK logs
interface IFlagshipLogManager {
emergency(message: string, tag: string): void;
alert(message: string, tag: string): void;
critical(message: string, tag: string): void;
error(message: string, tag: string): void;
warning(message: string, tag: string): void;
notice(message: string, tag: string): void;
info(message: string, tag: string): void;
debug(message: string, tag: string): void;
log(level: LogLevel, message: string, tag: string): void;
}
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 |
onSdkStatusChanged
The onSdkStatusChanged
function has one argument
Argument | Type | Description |
---|---|---|
status | number | Status of the SDK. seeFSSdkStatus |
FSSdkStatus)
FSSdkStatus
is an enum defining the different status of Flagship SDK
import { FSSdkStatus } from "@flagship.io/react-sdk";
const status = FSSdkStatus.SDK_INITIALIZED;
import { FSSdkStatus } from "https://deno.land/x/flagship_io_js_sdk/mod.ts";
const status = FSSdkStatus.SDK_INITIALIZED;
Key | Value | Type | Description |
---|---|---|---|
SDK_NOT_INITIALIZED | 0 | int | It is the default initial status. This status remains until the sdk has been initialized successfully. |
SDK_INITIALIZING | 1 | int | The SDK is currently initializing. |
SDK_PANIC | 2 | int | Flagship SDK is ready but is running in Panic mode: All features are disabled except the one which refreshes this status. |
SDK_INITIALIZED | 3 | int | The Initialization is done, and Flagship SDK is ready to use. |
onBucketingSuccess
The onBucketingSuccess
function has one argument with the following shape:
Key/Property | Type | Description |
---|---|---|
status | number | String. Returns either 200 (fresh update) or 304 (no change). |
payload | object | The latest bucketing data received. |
onBucketingFail
The onBucketingFail
function has one argument
Argument | Type | Description |
---|---|---|
error | object | Returns the error occurred |
onBucketingUpdated
The onBucketingUpdated
function has one argument
Argument | Type | Description |
---|---|---|
lastUpdate | Date | Get the date of the latest update |
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 a callback in the configuration option of the SDK.
The OnVisitorExposed
function accepts one argument with the following shape:
Argument | Type | Description |
---|---|---|
param | OnVisitorExposed | Get data from exposed flag |
OnVisitorExposed shape
type OnVisitorExposed ={
exposedVisitor: {
id: string
anonymousId?:string|null
context: Record<string, string|number|boolean>
},
fromFlag: {
key: string
value: unknown
defaultValue: unknown
metadata: IFSFlagMetadata
}
}
Key/Property | Type | Description |
---|---|---|
exposedVisitor | object | This object represent the exposed visitor |
fromFlag | object | This object represent the exposed flag. (The flag that has triggered the exposure) |
exposedVisitor object shape
Key/Property | Type | Description |
---|---|---|
id | string | visitor id |
anonomousId | string | anonymous id |
context | Record<string, string|number|boolean> | visitor context |
fromFlag object shape
Key/Property | Type | Description |
---|---|---|
key | string | flag key |
value | unknown | flag value |
defaultValue | unknown | flag default value |
metadata | IFSFlagMetadata | Campaign information metadata see |
Here is an example on how to use this callback:
Example with Mixpanel integration
Example with Segment integration
onFetchFlagsStatusChanged
The onFetchFlagsStatusChanged
function has one argument
Argument | Type | Description |
---|---|---|
status | number | Status of the SDK. seeFetchFlagsStatus |
FetchFlagsStatus
FetchFlagsStatus
is an object representing the status of visitor fetch for flag data.
type FetchFlagsStatus = {
/**
* The new status of the flags fetch.
*/
status: FSFetchStatus;
/**
* The reason for fetching Flags.
*/
reason: FSFetchReasons;
};
Key/Property | Type | Description |
---|---|---|
status | object | Enum representing the status of the flags in the Flagship SDK. |
reason | object | Enum representing the reasons for fetching Flags. |
FSFetchStatus enum
FSFetchStatus
is an enum representing the status of the flags in the visitor instance
Key | Type | Description |
---|---|---|
FETCHED | string | The flags have been successfully fetched from the API or re-evaluated in bucketing mode. |
FETCH_REQUIRED | string | The flags need to be re-fetched due to a change in context, or because the flags were loaded from cache or XPC. |
NOT_FOUND | string | The flag was not found or does not exist. |
PANIC | string | The SDK is in PANIC mode: All features are disabled except for the one to fetch flags. |
FSFetchReasons enum
FSFetchReasons
is an enum representing the reasons for re-fetching Flags.
Key | Type | Description |
---|---|---|
AUTHENTICATE | string | Indicates that the XPC method 'authenticate' has been called. |
FETCH_ERROR | string | Indicates that fetching flags has failed. |
NONE | string | Indicates that there is no specific reason for fetching flags. |
READ_FROM_CACHE | string | Indicates that flags have been fetched from the cache. |
UPDATE_CONTEXT | string | Indicates that a context has been updated or changed. |
UNAUTHENTICATE | string | Indicates that the XPC method 'unauthenticate' has been called. |
VISITOR_CREATED | string | Indicates that the visitor has been created. |
Tracking Manager Config
Represents the configuration for the tracking manager.
The Tracking Manager’s batch processing reduces network traffic, prevents hits loss through caching, and resends any failed hits.
options:
Key | Type | Default value | Description |
---|---|---|---|
cacheStrategy | CacheStrategy | number | CONTINUOUS_CACHING : 0 | Define the strategy that will be used for hit caching see cacheStrategy |
poolMaxSize | number | 10 | 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 | number | 5s | 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 10800s (3hours). Otherwise default value will be applied |
CacheStrategy
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: - It is Recommended for client side applications and should be used when your application is running in an environment where the probability of data loss is high.- The SDK has a default cache implementation for browser using localStorage - Keep in mind that this strategy can do a lot of database I/O depending on how many hits your visitor can send.see example using localStorage |
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: - It is recommended for server-side applications and should be used when your application sends a lot of hits and the probability of data loss is low. - The number of I/Os in the database is low.see example using redis |
import React from "react";
import { FlagshipProvider, CacheStrategy } from "@flagship.io/react-sdk";
const App = () => (
<>
<FlagshipProvider
envId="YOUR_ENV_ID"
apiKey="YOUR_API_KEY"
visitorData={{
id: "YOUR_VISITOR_ID",
hasConsented: true,
context: {
// some context
},
isAuthenticated: false,
}}
trackingManagerConfig={{
cacheStrategy: CacheStrategy.CONTINUOUS_CACHING,
poolMaxSize: 10,
batchIntervals: 5
}}
>
{/* [...] */}
</FlagshipProvider>
</>
);
useFlagship
hook
useFlagship
hookThis is the most frequently used hook from the Flagship React SDK. It provides additional functionalities such as retrieving the current flags of your actual visitor, sending hit tracking, checking SDK status, and more...
Returns an object. (Typescript: UseFlagshipOutput
)
Key/Property | Type | Description |
---|---|---|
visitorId | string | The unique visitor identifier. |
anonymousId | string | The anonymous visitor identifier. |
setConsent | function(hasConsented: boolean): void | Sets whether the visitor has consented for protected data usage. See description . |
hasConsented | boolean | Indicates whether the visitor has consented for protected data usage. |
updateContext | function(context: Record<string, boolean|string|number>): void | 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. See description. |
context | object | This property returns all the visitor's current context as an object |
clearContext | function(): void | Clear the actual visitor context. See description. |
fetchFlags | function(): Promise | Invokes the decision API or refers to the bucketing file to refresh all campaign flags based on the visitor's context.See description |
getFlag | function(key: string): object | Return a Flag object by its key. If no flag matches the given key, an empty flag will be returned. Call exists() to check if the flag has been found. See description |
getFlags | function(): object | Returns a collection of all flags fetched for the visitor. |
authenticate | function(visitorId: string): void | Authenticate anonymous visitor See description |
unauthenticate | function(): void | This function change authenticated Visitor to anonymous visitor. See description |
sdkStatus | FSSdkStatus | Return current status of Flagship SDK. seeFSSdkStatus |
fetchStatus | FetchFlagsStatus | The fetch status of the flags. see FetchFlagsStatus |
flagsData | array | An array of flag data |
sendHits | function(hit: object| object[]): Promise | Sends a hit to the Flagship server. See description |
close | function(): Promise | 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 Flagship class to avoid data loss.When called, it Batches and sends all hits that are in the pool before the application is closed. |
setConsent
method
setConsent
methodSets whether the visitor has consented for protected data usage.
setConsent(hasConsented: boolean): void
It accepts one argument:
Argument | Type | Default | Description |
---|---|---|---|
hasConsented | boolean | required | Set visitor consent for private data usage. When false some features will be deactivated. |
updateContext
method
updateContext
methodUpdate 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.
public updateContext(context: Record<string, string | number | boolean>): void
It has one argument :
Argument | Type | Description |
---|---|---|
context | object | A Set of keys, values. |
clearContext
method
clearContext
methodClear the actual visitor context
clearContext(): void
- 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
- Whenever you update visitor context, the SDK automatically re-fetches flags based on the updated context.
Context with predefined keys of context
Here's an example of how to use these predefined keys to update the visitor context in both Node.js and Deno environments:
import React from "react";
import { FlagshipProvider, DEVICE_LOCALE } from "@flagship.io/react-sdk";
const App = () => (
<>
<FlagshipProvider
envId="YOUR_ENV_ID"
apiKey="YOUR_API_KEY"
visitorData={{
hasConsented: true,
context: {
[DEVICE_LOCALE]: "fr",
},
}}
>
{/* [...] */}
</FlagshipProvider>
</>
);
import React from "react";
import { useFlagship } from "@flagship.io/react-sdk";
export const MyReactComponent = () => {
const { updateContext } = useFlagship()
return (
<button
onClick={()=>{
updateContext({
[DEVICE_LOCALE]: "fr"
})
}}>
Trigger update context
</button>
);
};
Here is the List of all predefined context keys.
fetchFlags
method
fetchFlags
methodInvokes the decision API
or refers to the bucketing file
to refresh all campaign flags based on the visitor's context.
fetchFlags(): Promise<void>
getFlag
method
getFlag
methodReturn a Flag object by its key. If no flag matches the given key, an empty flag will be returned. the exists()
method of the Flag object can be called to check if the flag has been found.
getFlag(key:string):IFlag
Arguments:
Name | Type | Description |
---|---|---|
key | String | The key associated to the flag. |
getFlags
method
getFlags
methodReturns a collection of all flags fetched for the visitor.
getFlags(): IFSFlagCollection
authenticate
method
authenticate
methodAuthenticate anonymous visitor
authenticate(visitorId: string): void
Argument | Type | Default | Description |
---|---|---|---|
visitorId | string | required | id of the new authenticated visitor. |
Information
- Whenever the
authenticate
method is called, the SDK automatically re-fetches flags.- The visitor targeting / Flags could change based on this new data.
unauthenticate
method
unauthenticate
methodThis function change authenticated Visitor to anonymous visitor
unauthenticate(): void
Information
- Whenever the
unauthenticate
method is called, the SDK automatically re-fetches flags.- The visitor targeting / Flags could change based on this new data.
sendHits
method
sendHits
methodThis method Sends a hit or multiple hits to the Flagship server.
send (hits: IHit| IHit[]): Promise<void>
Parameter:
name | Type | Default | Description |
---|---|---|---|
hits | object | required | Hits to send. see Hit |
useFsFlag
hook
useFsFlag
hookShortcut hook
The purpose of this hook is to rapidly get a flag.
This hook returns a Flag object by its key. If no flag matches the given key an empty flag will be returned.
useFsFlag<T>(key: string) : IFlag<T>
Argument | Type | Description |
---|---|---|
key | String | key associated to the flag. |
IFSFlag
interface
IFSFlag
interfaceThis interface represents a flag in the Flagship SDK
. It helps you retrieve the flag value, access flag metadata, expose the flag, verify the flag's existence, and get the flag status with the following API:
metadata
property
metadata
propertyIt returns an object that implements the IFSFlagMetadata interface, which contains the metadata of the campaign’s flag. If the flag doesn’t exist, it returns an empty object.
metadata:IFSFlagMetadata
status
property
status
propertyReturn the flag status.
status: FSFlagStatus
FSFlagStatus
is an enum representing the status of the flag
Key | Type | Description |
---|---|---|
FETCHED | string | The flags have been successfully fetched from the API or re-evaluated in bucketing mode. |
FETCH_REQUIRED | string | The flags need to be re-fetched due to a change in context, or because the flags were loaded from cache or XPC. |
NOT_FOUND | string | The flag was not found or does not exist. |
PANIC | string | The SDK is in PANIC mode: All features are disabled except for the one to fetch flags. |
getValue
method
getValue
methodReturns the value of the flag if the flag exists and the type of the default value matches the flag type value, otherwise it returns the default value.
getValue<T>(defaultValue: T, visitorExposed : boolean) : T
Argument:
Name | Type | Default Value | Description |
---|---|---|---|
defaultValue | T | Required | RequiredThe default value of the flag. |
visitorExposed | Boolean | true | Indicates to Flagship that the visitor have been exposed and have seen this flag. This will increment the visits for the current variation on your campaign reporting. It is possible to set this param to false and call visitorExposed() afterward when the visitor sees it. |
Information
- The default value must be one of the following type :
string
,number
,boolean
,object
,array
ornull
.- When the default value is
null
, no type checking will be performed
visitorExposed
method
visitorExposed
methodNotifies Flagship that the visitor has been exposed to and seen this flag.
visitorExposed(): Promise<void>
exists
method
exists
methodThis method checks if the flag exists.
exists(): boolean
IFSFlagCollection
interface
IFSFlagCollection
interfaceIt represents a collection of flags.
size
property
size
propertyGets the number of flags in the collection.
readonly size: number
get
method
get
methodIt returns the flag associated with the specified key, or an empty if the key is not found.
get(key: string): IFSFlag
Arguments:
Name | Type | Description |
---|---|---|
key | String | The key associated to the flag. |
has
method
has
methodChecks if the collection contains a flag with the specified key.
has(key: string): boolean
Arguments:
Name | Type | Description |
---|---|---|
key | String | The key associated to the flag. |
keys
method
keys
methodGets the keys of all flags in the collection.
keys(): Set<string>
filter
method
filter
methodIt filters the collection based on a predicate function and returns A new IFSFlagCollection containing the flags that satisfy the predicate.
filter(predicate: (value: IFSFlag, key: string, collection: IFSFlagCollection) => boolean): IFSFlagCollection;
Arguments:
Name | Type | Description |
---|---|---|
predicate | function | The predicate function used to filter the collection. |
exposeAll
method
exposeAll
methodExposes all flags in the collection.
exposeAll(): Promise<void>
getMetadata
method
getMetadata
methodA map containing the metadata for all flags in the collection.
getMetadata(): Map<string, IFSFlagMetadata>;
toJSON
method
toJSON
methodSerializes the metadata for all flags in the collection.
toJSON(): SerializedFlagMetadata[]
forEach
method
forEach
methodIterates over each flag in the collection.
forEach (callbackfn: (value: IFSFlag, key: string, collection: IFSFlagCollection) => void): void
IFSFlagMetadata
interface
IFSFlagMetadata
interfaceinterface IFSFlagMetadata{
campaignId:string
campaignName:string
variationGroupId:string
variationGroupName:string
variationId: string
variationName:string
isReference: boolean
campaignType: string
slug?:string|null
}
Key | Type | Description |
---|---|---|
campaignId | string | Campaign ID |
campaignName | string | Campaign name |
variationGroupId | string | Variation group ID |
variationGroupName | string | Variation group Name |
variationId | string | The variation ID assigned to the visitor |
variationName | string | Variation name |
isReference | boolean | Specify if its the reference variation |
campaignType | string | campaign type |
slug | string | campaign slug |
SerializedFlagMetadata
Key | Type | Description |
---|---|---|
key | string | Flag name |
campaignId | string | Campaign ID |
campaignName | string | Campaign name |
slug | string | campaign slug |
campaignType | string | campaign type |
variationGroupId | string | Variation group ID |
variationGroupName | string | Variation group name |
variationId | string | The variation ID assigned to the visitor |
variationName | string | Variation name |
isReference | boolean | Specify if its the reference variation |
hex | string | Reserved for Flagship |
Hit Tracking
This section guides you on how to track visitors in your application and learn how to build hits to feed your reports. For more details about our measurement protocol, refer to our Universal Collect documentation.
There are five different types of Hits:
- Page
- Screen
- Transaction
- Item
- Event
HitType
import React from "react";
import { useFlagship, HitType } from "@flagship.io/react-sdk";
export const MyReactComponent = () => {
const pageHit = {
type: HitType.PAGE,
documentLocation: "https://localhost",
}
return (
<>...</>
);
};
Key | type | Value | Description |
---|---|---|---|
PAGE | string | PAGEVIEW | Indicates a URL viewed by a visitor. |
SCREEN | string | SCREENVIEW | Indicates a screen viewed by a visitor. |
TRANSACTION | string | TRANSACTION | Indicates a transaction made by a visitor. |
ITEM | string | ITEM | Represents an item purchased in a transaction. |
EVENT | string | EVENT | Indicates a specific action performed by a visitor. |
Common Optional Parameters for Hits
import React from "react";
import { useFlagship, HitType } from "@flagship.io/react-sdk";
export const MyReactComponent = () => {
const fs = useFlagship()
return (
<button
onClick={()=>{
fs.sendHits({
documentLocation: "https://localhost",
userIp: "127.0.0.1",
screenResolution: "800X600",
locale: "fr",
sessionNumber: "1234"
})
}}>
Send a hit
</button>
);
};
Parameter | Type | Description |
---|---|---|
userIp | String | (Optional) Visitor's IP address |
screenResolution | string | (Optional) Screen resolution. |
locale | String | (Optional) Visitor's language |
sessionNumber | string | (Optional) Session number |
Page hit
This hit should be sent each time a visitor navigates to a new page.
It has the following structure:
Key/Property | Type | Default | Description |
---|---|---|---|
type | string (PAGEVIEW ) | required | type of hit. see HitType |
documentLocation | String | required | Valid url. |
Screen hit
This hit should be sent each time a visitor navigates to a new interface on the client side.
It has the following structure:
Key/Property | Type | Default | Description |
---|---|---|---|
type | string (SCREENVIEW ) | required | Type of hit. see HitType |
documentLocation | String | required | Name of screen. |
Transaction hit
This hit should be sent when a visitor completes a Transaction.
It has this following structure:
Key/Property | Type | Default | Description |
---|---|---|---|
type | string (TRANSACTION ) | required | Type of hit. see HitType |
transactionId | String | required | Unique identifier for your transaction. |
affiliation | String | required | The name of the KPI that you will have inside your reporting. Learn more |
totalRevenue | float | optional | The total revenue associated with the transaction, including any shipping and/or tax amounts. |
shippingCosts | float | optional | The total shipping cost of your transaction. |
shippingMethod | String | optional | The shipping method for your transaction. |
taxes | float | optional | Specifies the total amount of taxes in your transaction. |
currency | String | optional | Specifies the currency of your transaction. NOTE: This value should be a valid ISO 4217 currency code. |
paymentMethod | String | optional | Specifies the payment method used for your transaction. |
itemCount | int | optional | Specifies the number of items in your transaction. |
couponCode | String | optional | Specifies the coupon code used by the customer in your transaction. |
Item hit
This hit is used to associate an item with a transaction. It should be sent following the corresponding transaction hit.
It has this following structure:
Key/Property | Type | Default | Description |
---|---|---|---|
type | string (ITEM ) | required | Type of hit. see HitType |
transactionId | String | required | Unique identifier for your transaction. |
productName | String | required | Name of your item. |
productSku | String | required | SKU or item code. |
itemCategory | String | optional | Category to which the item belongs. |
itemPrice | float | optional | Price for a single item/unit. |
itemQuantity | int | optional | Specifies the number of items purchased. |
Information
The
Item
hit is not currently available in the Flagship reporting view.
Event hit
This hit can be used to track any event, such as a click on 'Add To Cart' or a newsletter subscription.
It has the following structure:
Key/Property | Type | Default | Description |
---|---|---|---|
type | string (EVENT ) | required | Type of hit. see HitType |
category | string | required | Category of your event. NOTE: This value must be either User Engagement or Action Tracking . |
action | string | required | Event name, which will also serve as the KPI in your reporting. Learn more |
label | string | optional | Additional description of your event. |
value | integer | optional | Can be used to evaluate visitor interactions with individual site objects or content items. NOTE: this value must be non-negative and not a float |
Cache management
The purpose of cache management is to address the following issues:
- Re-allocation in bucketing mode :
In bucketing mode, the SDK ensures that a visitor remains in the variation where they were initially allocated, even if the customer or dynamic allocation changes the traffic allocation. This is because in bucketing mode, the assignment is made on the local device, so changing campaign allocation on the platform could cause visitors to see different campaigns.
- Handle offline mode on client side :
When the cache is enabled, the SDK attempts to retrieve the latest visitor data (campaign assignments) from the cache. It also saves all failed hits and visitor exposures to resend them later.
By default, the Flagship JS SDK provides a default cache manager implementation on the client side. However, you can use your own cache manager by implementing the IVisitorCacheImplementation
and IHitCacheImplementation
interfaces through the visitorCacheImplementation and hitCacheImplementation properties of the configuration.
Visitor Cache
The visitor cache is used to store the visitor data in a database through the IVisitorCacheImplementation
interface which defines the methods that an object must implement to manager it.
interface IVisitorCacheImplementation {
cacheVisitor(visitorId: string, data: VisitorCacheDTO):Promise<void>
lookupVisitor(visitorId: string): Promise<VisitorCacheDTO>
flushVisitor(visitorId: string): Promise<void>
}
cacheVisitor
method
cacheVisitor
methodThis method is invoked when the SDK needs to store visitor information in your database.
public cacheVisitor(visitorId: string, data: object):Promise<void>
It accepts 2 arguments :
Argument | Type | Description |
---|---|---|
visitorId | string | The ID of the visitor |
Data | object | The visitor data. The object adheres to the structure of the VisitorCacheDTO type. |
lookupVisitor
method
lookupVisitor
methodThis method is invoked when the SDK needs to retrieve visitor information associated with a specific visitor ID from your database.
It should return an object of type VisitorCacheDTO
that adheres to this structure see.
public lookupVisitor(visitorId: string): Promise<object>
It accepts one argument :
Argument | Type | Description |
---|---|---|
visitorId | string | visitor ID |
flushVisitor
method
flushVisitor
methodThis method is invoked when the SDK needs to delete the visitor information associated with a specific visitor ID from your database.
public flushVisitor(visitorId: string): Promise<void>
It accepts one argument :
Argument | Type | Description |
---|---|---|
visitorId | string | The ID of the visitor |
Information
- This method is called every time the
setConsent
method or the hasConsented key of the props visitorData is set tofalse
.
VisitorCacheDTO
type VisitorCacheDTO = {
version: number;
data: {
visitorId: string;
anonymousId: string | null;
consent?: boolean;
context?: Record<string, boolean|number|string>;
assignmentsHistory?: Record<string, string>;
campaigns?: Array<{
campaignId: string;
variationGroupId: string;
variationId: string;
isReference?: boolean;
type: string;
activated?: boolean;
flags?: Record<string, unknown>;
}>;
};
};
Hit Cache
The hit cache is used to store hits in your database based on the strategy used through the IHitCacheImplementation
interface which defines the methods that an object must implement to handle it.
interface IHitCacheImplementation {
cacheHit(hits: Record<string, HitCacheDTO>):Promise<void>
lookupHits():Promise<Record<string, HitCacheDTO>>
flushHits(hitKeys: string[]): Promise<void>
flushAllHits(): Promise<void>
}
cacheHit
method
cacheHit
methodThis method is invoked to store hits based on cache the strategy used.
public cacheHit(hits: Record<string, HitCacheDTO>):Promise<void>
It accepts 1 argument :
Argument | Type | Description |
---|---|---|
hits | object | This is a key/value object where: - key is a unique ID for each hit - value is an object that follows the shape of type HitCacheDTO . |
lookupHits
method
lookupHits
methodThis method is invoked to load all hits from your database and attempt to send them in the background.
It should return an object where the key is a unique ID for each hit, and the value is an object of type HitCacheDTO
that adheres to this structure see.
public lookupHits():Promise<Record<string, HitCacheDTO>>
Information
Hits
older than 4H will be ignored during the re-sending process.
flushHits
function
flushHits
functionThis method is invoked to delete all hits that match the unique hit IDs from your database.
NOTE: It is called every time setConsent
is set to false, erasing all of the visitor's hits from the database.
public flushHits(hitKeys: string[]): Promise<void>
It accepts one argument :
Argument | Type | Description |
---|---|---|
hitKeys | Array | Unique ID of hits |
- This method is called every time the
setConsent
method or the hasConsented key of the props visitorData is set tofalse
.
flushAllHits
function
flushAllHits
functionThis method is invoked to delete all hits from your database without exception.
public flushAllHits(): Promise<void>
HitCacheDTO
type HitCacheLookupDTO = {
version: number;
data: {
visitorId: string;
anonymousId: string | null;
type: HitType | "ACTIVATE";
time: number;
content?: Record<string, unknown>;
};
};
IHitCacheImplementation
implementation
IHitCacheImplementation
implementationlocalStorage
This is an implementation of the IHitCacheImplementation
interface using localStorage
.
import { Flagship, CacheStrategy } from "@flagship.io/react-sdk";
const FS_HIT_PREFIX = 'FS_DEFAULT_HIT_CACHE'
const hitCacheImplementation = {
cacheHit (hits) {
const localDatabaseJson = localStorage.getItem(FS_HIT_PREFIX) || '{}'
const localDatabase = JSON.parse(localDatabaseJson)
const newLocalDatabase = {
...localDatabase,
...hits
}
localStorage.setItem(FS_HIT_PREFIX, JSON.stringify(newLocalDatabase))
return Promise.resolve()
},
lookupHits () {
const localDatabaseJson = localStorage.getItem(FS_HIT_PREFIX) || '{}'
const localDatabase = JSON.parse(localDatabaseJson)
return Promise.resolve(localDatabase)
},
flushHits (hitKeys) {
const localDatabaseJson = localStorage.getItem(FS_HIT_PREFIX) || '{}'
const localDatabase = JSON.parse(localDatabaseJson)
hitKeys.forEach(key => {
delete localDatabase[key]
})
localStorage.setItem(FS_HIT_PREFIX, JSON.stringify(localDatabase))
return Promise.resolve()
},
flushAllHits () {
localStorage.removeItem(FS_HIT_PREFIX)
return Promise.resolve()
}
}
Flagship.start(ENV_ID, API_KEY, {
hitCacheImplementation: hitCacheImplementation,
trackingManagerConfig: {
batchIntervals: 5,
poolMaxSize: 10,
cacheStrategy: CacheStrategy.CONTINUOUS_CACHING
}
})
Redis
This is an implementation of the IHitCacheImplementation
interface using redis
.
import { Flagship, CacheStrategy } from "@flagship.io/react-sdk";
import Redis from 'ioredis'
function hitCacheImplementation (host, port, dbIndex) {
const redis = new Redis({
host,
port
})
redis.select(dbIndex)
return {
async cacheHit (hits) {
const multi = redis.multi()
Object.entries(hits).forEach(([key, value]) => {
multi.set(key, JSON.stringify(value))
})
await multi.exec()
},
async lookupHits () {
const hits:Record<string, HitCacheDTO> = {}
const keys = await redis.keys('*')
if (!keys.length) {
return hits
}
const redisData = await redis.mget(keys)
redisData.forEach((value, index) => {
if (!value) {
return
}
hits[keys[index]] = JSON.parse(value)
})
return hits
},
async flushHits (hitKeys) {
await redis.del(hitKeys)
},
async flushAllHits () {
const keys = await redis.keys('*')
if (!keys.length) {
return
}
await redis.del(keys)
}
}
}
Flagship.start(ENV_ID, API_KEY, {
hitCacheImplementation:hitCacheImplementation('127.0.0.1', '6379', 2),
trackingManagerConfig: {
batchIntervals: 10,
poolMaxSize: 100,
cacheStrategy: CacheStrategy.PERIODIC_CACHING
}
})
In the LocalStorage implementation, the localStorage
web API is used to store, retrieve, and delete hits. In the Redis implementation, the ioredis
library is used to interact with a Redis database for the same purposes. Both implementations are passed to the Flagship.start
method as part of the configuration object.
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.
All possible predefined keys are listed below:
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 |
OS_NAME | Name of the OS | sdk_osName | String | No | 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 | 4.0.0 |
FLAGSHIP_VISITOR | Current visitor id (Reserved) | fs_users | String | Yes | visitor_id |
Updated 6 months ago