Quick-start

Installation

Refer to the installation page for installation steps.

Flagship Usage

Initialization

Client-side Rendering

Step 1: Initialize the SDK with FlagshipProvider. This is usually done in your App.js file to ensure your entire application is wrapped with the provider. Ensure also to include the required props such as envId, apiKey, and visitorData.

JSX

import React from "react";
import { FlagshipProvider } from "@flagship.io/react-sdk";

const App = () => (
  <>
    <FlagshipProvider
      envId="YOUR_ENV_ID"
      apiKey="YOUR_API_KEY"
      visitorData={{
        id: "YOUR_VISITOR_ID",
        hasConsented: true, // This is required
        context: {
          key:"value"
        },
      }}
    >
      {/* ... */}
    </FlagshipProvider>
  </>
);

👍

Good to know

• When the SDK is started with all the required props, it automatically fetches flags based on visitorData provided. No additional action is necessary. For more details

• The key hasConsented is required in the visitorData props.

Server-side Rendering with Next.js 13+

For Next.js 13+ applications using the App Router, use FlagshipProviderSSR. This async server Provider prefetches all flags during server rendering:

A comprehensive example can be found here .

JSX

// In Next.js 13+ app/layout.tsx or any server component
import { FlagshipProviderSSR, LogLevel, DecisionMode } from "@flagship.io/react-sdk";

// Server component (default in Next.js 13+ App Router)
export default async function Layout({ children }) {
  return (
    <FlagshipProviderSSR
      envId="YOUR_ENV_ID"
      apiKey="YOUR_API_KEY"
      visitorData={{
        id: "YOUR_VISITOR_ID",
        hasConsented: true,
        context: {
          key: "value"
        },
      }}
      // Optional configuration
      logLevel={LogLevel.DEBUG}
      decisionMode={DecisionMode.DECISION_API}
      fetchNow={true}
    >
      {children}
    </FlagshipProviderSSR>
  );
}

👍 Good to know

• FlagshipProviderSSR prefetches flags on the server before sending HTML to the client, eliminating flag flickering

• Once the application hydrates on the client side, it behaves like a normal FlagshipProvider without needing to re-fetch flags

• This approach provides the best of both worlds: server-rendered initial content with the pre-fetched flags, followed by client-side interactivity

• Perfect for Next.js 13+ App Router where components are server components by default

Getting Flags

Steps 2 and 3 involve retrieving your flag, and reading your flag's value.

The React SDK provides two ways to retrieve a flag object. This object includes methods to retrieve the flag value, access flag metadata, expose the flag, verify the flag's existence, and get the flag status.

You have two options:

• Use the useFsFlag hook

• or use the useFlagship hook

With useFsFlag hookWith useFlagship hook

import React from "react";
import { useFsFlag } from "@flagship.io/react-sdk";

export const MyReactComponent = () => {
  ///Step 2:  Retrieves a flag named "backgroundColor"
  const flag = useFsFlag("backgroundColor")
  
  //Step 3: Returns the value of the flag or if the flag does not exist, it returns the default value "green" 
  const flagValue = flag.getValue("green")
  
  return (
    <button
      style={{
        height: "200px",
        width: "200px",
        backgroundColor: flagValue,
      }}
    >
      {"I'm a square with color=" + flagValue}
    </button>
  );
};

👍 Good to know

• By default, the SDK assumes that the visitor has been exposed to the flag when flag.getValue() is called, so it sends the flag exposure hit to flagship server. However, this behavior can be changed. Click here for more details

• These hooks are designed to be used in a component that is either within the FlagshipProvider or a descendant of a component within FlagshipProvider.

Tracking hits

Step 4: Send hits to Flagship using the sendHits method from the useFlagship hook. These hits help validate your objectives (KPIs) set up in your campaign.

JSX

import React from "react";
import { useFlagship, HitType } from "@flagship.io/react-sdk";

export const MyReactComponent = () => {
  const fs = useFlagship()
  
  return (
    <button
    	onClick={()=>{
        //Step 4: Send a hit
  			fs.sendHits({
          type: HitType.EVENT, 
          category: EventCategory.USER_ENGAGEMENT,
          action: "click",
          label: "label",
          value: 100,
        })
  		}}
    >
      Send a hit
    </button>
  );
};