@d11/flagship-rn-sdk

@d11/flagship-rn-sdk

A React Native SDK for managing feature flags with support for dynamic configuration, context-based targeting, and real-time flag evaluation.

Features

• ✅ Easy Integration: Simple API for React Native applications
• ✅ Type-Safe: Full TypeScript support
• ✅ Context-Based Targeting: Evaluate flags based on user context
• ✅ Multiple Value Types: Support for boolean, string, integer, double, and object values
• ✅ Auto-Refresh: Configurable polling interval for flag updates
• ✅ Expo Compatible: Works seamlessly with Expo projects
• ✅ Cross-Platform: Works on both iOS and Android

Installation

npm install @d11/flagship-rn-sdk

or

yarn add @d11/flagship-rn-sdk

Setup

React Native (Bare Workflow)

iOS

• Install pods:

cd ios && pod install && cd ..

• The SDK automatically configures the necessary Podfile settings for static frameworks.

Android

The SDK requires GitHub credentials to access the Android SDK dependency from GitHub Packages. You need to set these credentials before building your Android app.

Option 1: Using Environment Variables (Recommended)

Set the following environment variables in your system:

export GITHUB_USERNAME=your-github-username
export GITHUB_TOKEN=your-github-pat-token

Option 2: Using Gradle Properties

Add the credentials to your android/gradle.properties file (or ~/.gradle/gradle.properties for global configuration):

GITHUB_USERNAME=your-github-username
GITHUB_TOKEN=your-github-pat-token

When are credentials needed?

• During gradle build or ./gradlew build
• When running npm run android or yarn android
• When Android Studio syncs the project
• During CI/CD builds

Note: The credentials are only used to download the Android SDK dependency from GitHub Packages. They are not included in your app bundle.

Usage

1. Initialize the SDK

Initialize the SDK with your configuration before using any flag evaluation methods:

import { initialize } from '@d11/flagship-rn-sdk';

await initialize({
  baseUrl: 'https://api.example.com',
  tenantId: 'your-tenant-id',
  refreshInterval: 60, // in seconds (default: 30)
});

Configuration Options:

• baseUrl (string, required): Base URL of your feature flag service
• tenantId (string, required): Your tenant identifier
• refreshInterval (number, optional): Polling interval in seconds (default: 30)

2. Set User Context

Set the user context to enable context-based flag targeting:

import { setContext } from '@d11/flagship-rn-sdk';

await setContext({
  targetingKey: 'user-123',
  user_tier: 'premium',
  country: 'US',
  is_logged_in: true,
  session_count: 5,
  profile: {
    age: 25,
    city: 'New York',
  },
});

Context Requirements:

• targetingKey (string, required): Unique identifier for the user/context
• Additional fields: Any number of additional context fields (string, number, boolean, Date, array, or object)

3. Get Flag Values

Evaluate feature flags with type-safe methods:

Boolean Flags

import { getBooleanValue } from '@d11/flagship-rn-sdk';

const darkModeEnabled = await getBooleanValue('dark_mode', false);
if (darkModeEnabled) {
  // Enable dark mode
}

String Flags

import { getStringValue } from '@d11/flagship-rn-sdk';

const theme = await getStringValue('app_theme', 'light');

Integer Flags

import { getIntegerValue } from '@d11/flagship-rn-sdk';

const maxItems = await getIntegerValue('max_cart_items', 10);

Double Flags

import { getDoubleValue } from '@d11/flagship-rn-sdk';

const discountRate = await getDoubleValue('discount_rate', 0.0);

Object Flags

import { getObjectValue } from '@d11/flagship-rn-sdk';

const config = await getObjectValue('app_config', {});

Complete Example

import React, { useEffect, useState } from 'react';
import { View, Text } from 'react-native';
import {
  initialize,
  setContext,
  getBooleanValue,
  getStringValue,
} from '@d11/flagship-rn-sdk';

export default function App() {
  const [isReady, setIsReady] = useState(false);
  const [darkMode, setDarkMode] = useState(false);
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    async function setupFlags() {
      // Initialize SDK
      await initialize({
        baseUrl: 'https://api.example.com',
        tenantId: 'your-tenant-id',
        refreshInterval: 60,
      });

      // Set user context
      await setContext({
        targetingKey: 'user-123',
        user_tier: 'premium',
        country: 'US',
      });

      // Evaluate flags
      const darkModeFlag = await getBooleanValue('dark_mode', false);
      const themeFlag = await getStringValue('app_theme', 'light');

      setDarkMode(darkModeFlag);
      setTheme(themeFlag);
      setIsReady(true);
    }

    setupFlags();
  }, []);

  if (!isReady) {
    return <Text>Loading...</Text>;
  }

  return (
    <View style={{ backgroundColor: darkMode ? '#000' : '#fff' }}>
      <Text>Theme: {theme}</Text>
    </View>
  );
}

API Reference

initialize(config: InitializeConfig): Promise<boolean>

Initializes the SDK with the provided configuration.

Parameters:

• config.baseUrl (string): Base URL for the feature flag service
• config.tenantId (string): Tenant identifier
• config.refreshInterval (number, optional): Polling interval in seconds (default: 30)

Returns: Promise<boolean> - true if initialization succeeds

setContext(context: SetContextConfig): Promise<boolean>

Sets the user context for flag evaluation.

Parameters:

• context.targetingKey (string, required): Unique user identifier
• context[key: string] (ContextValue): Additional context fields

Returns: Promise<boolean> - true if context is set successfully

Context Value Types:

• string
• number
• boolean
• Date
• ContextValue[] (array)
• { [key: string]: ContextValue } (object)

getBooleanValue(key: string, defaultValue: boolean): Promise<boolean>

Gets a boolean flag value.

Parameters:

• key (string): Flag key
• defaultValue (boolean): Default value if flag is not found

Returns: Promise<boolean> - Flag value or default

getStringValue(key: string, defaultValue: string): Promise<string>

Gets a string flag value.

Parameters:

• key (string): Flag key
• defaultValue (string): Default value if flag is not found

Returns: Promise<string> - Flag value or default

getIntegerValue(key: string, defaultValue: number): Promise<number>

Gets an integer flag value.

Parameters:

• key (string): Flag key
• defaultValue (number): Default value if flag is not found

Returns: Promise<number> - Flag value or default

getDoubleValue(key: string, defaultValue: number): Promise<number>

Gets a double/float flag value.

Parameters:

• key (string): Flag key
• defaultValue (number): Default value if flag is not found

Returns: Promise<number> - Flag value or default

getObjectValue(key: string, defaultValue: Object): Promise<Object>

Gets an object flag value.

Parameters:

• key (string): Flag key
• defaultValue (Object): Default value if flag is not found

Returns: Promise<Object> - Flag value or default

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. Import types as needed:

import type { InitializeConfig, SetContextConfig, ContextValue } from '@d11/flagship-rn-sdk';

Troubleshooting

iOS Build Issues

If you encounter build issues on iOS:

• Clean build folder: cd ios && xcodebuild clean && cd ..
• Reinstall pods: cd ios && pod deintegrate && pod install && cd ..
• Ensure deployment target is iOS 15.1 or higher

Default Values Always Returned

If flags always return default values:

• Verify baseUrl is correct and accessible
• Check tenantId matches your configuration
• Ensure setContext is called with valid targetingKey
• Check network connectivity

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library