@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: Automatic plugin configuration for 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 dynamic frameworks.

Android

No additional setup required. The SDK is automatically linked.

Expo

The SDK includes an Expo config plugin that automatically configures your project. The plugin is applied automatically when you install the package.

For Expo projects:

• Install the package:

npx expo install @d11/flagship-rn-sdk

• Run prebuild (if using bare workflow or custom native code):

npx expo prebuild

The plugin automatically:

• Configures use_frameworks! in your Podfile
• Sets up BUILD_LIBRARY_FOR_DISTRIBUTION for required dependencies

Manual Configuration (Optional):

If you need to manually configure the plugin, add it to your app.json:

{
  "expo": {
    "plugins": [
      "@d11/flagship-rn-sdk/expo-plugin-flagship-rn-sdk.js"
    ]
  }
}

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

Expo Plugin Not Working

If the Expo plugin doesn't apply automatically:

• Manually add to app.json:

{
  "expo": {
    "plugins": [
      "@d11/flagship-rn-sdk/expo-plugin-flagship-rn-sdk.js"
    ]
  }
}

• Run npx expo prebuild --clean

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