# Reference
## `FlagshipProvider`
Here is the full list of props available to use in the `FlagshipProvider` React component:
```
Type
Default
Description
```
```
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`](#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](#visitordata) \*\*
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 flags 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](#serializedflagmetadata) 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](#onfetchflagsstatuschanged)
timeout
number
2
The timeout in seconds for API requests.
Timeout can't be lower than 0 second.
logLevel
number
9
The maximum log level to display. [see`LogLevel`](#loglevel)
logManager
object
Defined
A custom implementation of the LogManager interface to receive logs from the SDK.
The object must fill the Interface [`IFlagshipLogManager`](#iflagshiplogmanager)
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 time in seconds between two bucketing polling requests.
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.
If the value is 0, no deduplication process will be applied.
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`](#visitor-cache) interface to handle the visitor cache. [see cache management](#cache-management)
hitCacheImplementation
object
Defined
**Optional**\
An object that implements the [`IHitCacheImplementation`](#hit-cache) , interface to manage hits cache. [see cache management](#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](#cache-management)
onSdkStatusChanged
function(number):void
undefined
**Optional**\
A callback function to be called when the SDK status has changed. [see arguments](#onsdkstatuschanged).
onBucketingSuccess
function(object):void
undefined
**Optional**\
A callback function to be called when the first bucketing polling succeeds. [see arguments](#onbucketingsuccess)
onBucketingFail
function(error):void
undefined
**Optional**\
A callback function to be called when the first bucketing polling fails. [see arguments](#onbucketingfail)
onBucketingUpdated
function(object):void
undefined
**Optional**\
A callback function to be called each time bucketing data from Flagship has been updated. [see arguments](#onbucketingupdated)
**Optional**\
A callback function to be called whenever the SDK needs to report a log.
[see arguments](#onlog)
trackingManagerConfig
object
defined
Options to configure hit batching.\
[trackingManagerConfig](#tracking-manager-config)
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](#onvisitorexposed)
fetchThirdPartyData
boolean
false
**Optional**\
**Bucketing mode only**
If true, the SDK will fetch the visitor's segment from the [universal data connector](https://developers.abtasty.com/docs/data/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](https://nextjs.org/docs/app/building-your-application/data-fetching/caching#per-request-caching)
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 applied.
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.
```
| Attribute |
| --------- |
| envId |
> ๐ 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](#managing-visitor-campaigns)
> * If the props `visitorData` is null, no visitor will be initialized until it is set
> * When both `initialCampaigns` and `initialFlags` are provided, the system will disregard `initialCampaigns` and only use `initialFlags`.
> * 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
```
Type
Default
Description
```
```
string
undefined
***Optional***
Unique visitor identifier.
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.
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.
```
| key |
| --- |
| id |
### Decision Mode
**`DECISION-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)
`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`](#loglevel) |
| tag | string | Get the function that triggered the log |
| message | string | Get a description of the log |
```typescript
import { LogLevel, FlagshipProvider } from "@flagship.io/react-sdk";
const App = () => (
<>
{
console.log(`[${LogLevel[level]}] [${tag}] : ${message}`)
}}
>
{/* [...] */}
)
```
### 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
```typescript
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;
}
```
```
Type
Description
```
```
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`](#loglevel)
```
| Argument |
| -------- |
| message |
### onSdkStatusChanged
The `onSdkStatusChanged` function has one argument
| Argument | Type | Description |
| -------- | ------ | --------------------------------------------------- |
| status | number | Status of the SDK. [see`FSSdkStatus`](#fssdkstatus) |
### FSSdkStatus)
`FSSdkStatus` is an enum defining the different status of Flagship SDK
```typescript
import { FSSdkStatus } from "@flagship.io/react-sdk";
const status = FSSdkStatus.SDK_INITIALIZED;
```
```typescript
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**
```typescript
type OnVisitorExposed ={
exposedVisitor: {
id: string
anonymousId?:string|null
context: Record
},
fromFlag: {
key: string
value: unknown
defaultValue: unknown
metadata: IFSFlagMetadata
}
}
```
```
Type
Description
```
```
object
This object represent the exposed visitor
fromFlag
object
This object represent the exposed flag.
(The flag that has triggered the exposure)
```
| Key/Property |
| -------------- |
| exposedVisitor |
**exposedVisitor** object shape
| Key/Property | Type | Description |
| ------------ | ---------------------------------------- | --------------- |
| id | string | visitor id |
| anonomousId | string | anonymous id |
| context | Record\ | 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](#ifsflagmetadata-interface) |
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)
### onFetchFlagsStatusChanged
The `onFetchFlagsStatusChanged` function has one argument
| Argument | Type | Description |
| -------- | ------ | ------------------------------------------------------------- |
| status | number | Status of the SDK. [see`FetchFlagsStatus`](#fetchflagsstatus) |
#### **FetchFlagsStatus**
`FetchFlagsStatus` is an object representing the status of visitor fetch for flag data.
```typescript
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:**
```
Type
Default value
Description
```
```
CacheStrategy | number
`CONTINUOUS_CACHING`: 0
Define the strategy that will be used for hit caching
[see cacheStrategy](#cachestrategy)
poolMaxSize
number
`10`
Define the minimum number of hits the pool must reach to automatically batch all hits in the pool and send them.
The value must be greater than 5 otherwise default value will be used
Note: Having a large poolMaxSize can lead to performance issues
batchIntervals
number
`5s`
Define a regular interval in seconds to trigger batch process.
The process will batch all hits from the pool whether `poolMaxSize` is reached or not
The value must be between 1 second and 10800s (3 hours). Otherwise default value will be applied
```
| Key |
| ------------- |
| cacheStrategy |
#### CacheStrategy
`cacheStrategy` is an enum defining the different caching strategies
```
Type
value
Description
```
```
number
0
When a hit is emitted, it will first be cached in database using [IHitCacheImplementation](#hit-cache), added into the pool, then after batching and sending, it will be flushed from database using [IHitCacheImplementation](#hit-cache).
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](#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](#hit-cache) for both actions.
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](#redis)
```
| Key |
| --------------------- |
| CONTINUOUS\\\_CACHING |
```jsx
import React from "react";
import { FlagshipProvider, CacheStrategy } from "@flagship.io/react-sdk";
const App = () => (
<>
{/* [...] */}
);
```
\\
## `useFlagship` hook
This 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`)*
```
Type
Description
```
```
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](#setconsent-method) .
hasConsented
boolean
Indicates whether the visitor has consented for protected data usage.
updateContext
function(context: Record\): 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](#updatecontext-method).
context
object
This property returns all the visitor's current context as an object
clearContext
function(): void
Clear the actual visitor context.
[See description](#clearcontext-method).
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](#fetchflags-method)
getFlag
function(key: string): object
Return a [Flag](#flag-class) 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](#getflag-method)
getFlags
function(): object
Returns a [collection](#ifsflagcollection) of all flags fetched for the visitor.
This function change authenticated Visitor to anonymous visitor.
[See description](#unauthenticate-method)
sdkStatus
FSSdkStatus
Return current status of Flagship SDK. [see`FSSdkStatus`](#fssdkstatus)
fetchStatus
FetchFlagsStatus
The fetch status of the flags. [see FetchFlagsStatus](#fetchflagsstatus)
flagsData
object\[]
An array of [flag data](#flag-data-shape)
sendHits
function(hit: object| object\[]): Promise\
Sends a hit to the Flagship server. **[See description](#sendhits-method)**
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.
```
| Key/Property |
| ------------ |
| visitorId |
### `setConsent` method
Sets 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
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.
* **`public updateContext(context: Record): void`**
It has one argument :
| Argument | Type | Description |
| -------- | ------ | ---------------------- |
| context | object | A Set of keys, values. |
### `clearContext` method
Clear 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:
```jsx
import React from "react";
import { FlagshipProvider, DEVICE_LOCALE } from "@flagship.io/react-sdk";
const App = () => (
<>
{/* [...] */}
);
```
```jsx
import React from "react";
import { useFlagship } from "@flagship.io/react-sdk";
export const MyReactComponent = () => {
const { updateContext } = useFlagship()
return (
);
};
```
[Here](#predefined-visitor-context-keys) is the List of all predefined context keys.
### `fetchFlags` method
Invokes the `decision API` or refers to the `bucketing file` to refresh all campaign flags based on the visitor's context.
* **`fetchFlags(): Promise`**
### `getFlag` method
Return a [Flag](#flag-class) object by its key. If no flag matches the given key, an empty flag will be returned. the `exists()` method of the [Flag](#flag-class) 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
Returns a [collection](#ifsflagcollection) of all flags fetched for the visitor.
* **`getFlags(): IFSFlagCollection`**
### `authenticate` method
Authenticate 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
This 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
This method Sends a hit or multiple hits to the Flagship server.
* **`send (hits: IHit| IHit[]): Promise`**
Parameter:
| name | Type | Default | Description |
| ---- | ------ | -------- | ------------------------------ |
| hits | object | required | Hits to send. [see Hit](#page) |
\\
## `useFsFlag` hook
> ๐ Shortcut hook
>
> The purpose of this hook is to rapidly get a flag.
This hook returns a [Flag](#flag-class-api) object by its key. If no flag matches the given key an empty flag will be returned.
* **`useFsFlag(key: string) : IFlag`**
| Argument | Type | Description |
| -------- | ------ | --------------------------- |
| key | String | key associated to the flag. |
\\
## `IFSFlag` interface
This 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
It returns an object that implements the [IFSFlagMetadata](#ifsflagmetadata-interface) 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
Return 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
Returns 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(defaultValue: T, visitorExposed : boolean) : T`**
Argument:
```
Type
Default Value
Description
```
```
T
`Required`
* \*Required\*\*The 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.
```
| Name |
| ------------ |
| defaultValue |
> ๐ Information
>
> * The default value must be one of the following type : `string`, `number`, `boolean`, `object`, `array` or `null`.
> * When the default value is `null`, no type checking will be performed
### `visitorExposed` method
Notifies Flagship that the visitor has been exposed to and seen this flag.
* **`visitorExposed(): Promise`**
### `exists` method
This method checks if the flag exists.
* **`exists(): boolean`**
\\
## `IFSFlagCollection` interface
It represents a collection of flags.
### `size` property
Gets the number of flags in the collection.
* **`readonly size: number`**
### `get` method
It returns the [flag](#ifsflag-interface) 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
Checks 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
Gets the keys of all flags in the collection.
* **`keys(): Set`**
### `filter` method
It filters the collection based on a predicate function and returns A new [IFSFlagCollection](#ifsflagcollection-interface) 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
Exposes all flags in the collection.
* **`exposeAll(): Promise`**
### `getMetadata` method
A map containing the [metadata](#ifsflagmetadata-interface) for all [flags](#ifsflag-interface) in the collection.
* **`getMetadata(): Map;`**
### `toJSON` method
Serializes the [metadata](#ifsflagmetadata-interface) for all flags in the collection.
* **`toJSON(): SerializedFlagMetadata[]`**
### `forEach` method
Iterates over each flag in the collection.
* **`forEach (callbackfn: (value: IFSFlag, key: string, collection: IFSFlagCollection) => void): void`**
\\
## `IFSFlagMetadata` interface
```typescript
interface 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](doc:universal-collect-documentation).
There are five different types of Hits:
* Page
* Screen
* Transaction
* Item
* Event
### HitType
```jsx
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
```jsx
import React from "react";
import { useFlagship, HitType } from "@flagship.io/react-sdk";
export const MyReactComponent = () => {
const fs = useFlagship()
return (
);
};
```
| 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](#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](#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](#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**](https://github.com/flagship-io/Gitbook/blob/main/docs/glossary/README.md#kpi) |
| 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](#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:
```
Type
Default
Description
```
```
string (`EVENT`)
required
Type of hit. [see HitType ](#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](/docs/glossary#kpi)**
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
```
| Key/Property |
| ------------ |
| type |
\\
## 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](#advanced-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.
```typescript
interface IVisitorCacheImplementation {
cacheVisitor(visitorId: string, data: VisitorCacheDTO):Promise
lookupVisitor(visitorId: string): Promise
flushVisitor(visitorId: string): Promise
}
```
#### `cacheVisitor` method
This method is invoked when the SDK needs to store visitor information in your database.
* **`public cacheVisitor(visitorId: string, data: object):Promise`**
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`](#visitorcachedto) type. |
#### `lookupVisitor` method
This 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](#visitorcachedto).
* **`public lookupVisitor(visitorId: string): Promise