Mobilev1.2.1

React Native SDK

Add feature flags to your React Native mobile application with hooks and context providers. Uses polling for flag updates and shares the same hooks API as the React SDK.

Installation

npm install @rollgate/sdk-react-native
# or
yarn add @rollgate/sdk-react-native
# or
pnpm add @rollgate/sdk-react-native

Quick Start

1. Add the Provider

Wrap your application with RollgateProvider:

App.tsx

import { RollgateProvider } from '@rollgate/sdk-react-native';

export default function App() {
  return (
    <RollgateProvider
      apiKey="rg_client_..."
      baseUrl="https://api.rollgate.io"
    >
      <Navigation />
    </RollgateProvider>
  );
}

2. Use the Hook

Access flags in your screens and components with useFlag:

screens/HomeScreen.tsx

import { useFlag } from '@rollgate/sdk-react-native';

function HomeScreen() {
  const showNewUI = useFlag('new-home-ui', false);

  if (showNewUI) {
    return <NewHomeUI />;
  }
  return <LegacyHomeUI />;
}

Provider Props

Prop	Type	Default	Description
apiKey	string	required	Your Rollgate client API key
baseUrl	string	'https://api.rollgate.io'	Rollgate API base URL
refreshInterval	number	30000	Polling interval in milliseconds
user	UserContext	undefined	Initial user context for targeting

Note: The React Native SDK uses polling only. SSE streaming is not supported on mobile due to platform constraints. Use refreshInterval to control how frequently flags are updated.

Hooks

useFlag

Check if a single flag is enabled:

const isEnabled = useFlag('flag-key', defaultValue);

Prop	Type	Default	Description
flagKey	string	required	The flag key to check
defaultValue	boolean	false	Value to return if flag not found

useFlags

Get all flags at once:

const { flags, isLoading, error } = useFlags();

// Access individual flags
if (flags['new-feature']) {
  // ...
}

useRollgate

Access the full Rollgate context for advanced use cases:

const {
  flags,
  isLoading,
  error,
  identify,  // Set user context
  refresh,   // Force refresh flags
} = useRollgate();

// Identify user after login
await identify({
  id: 'user-123',
  email: '[email protected]',
  attributes: { plan: 'pro' }
});

User Targeting

Pass user information to enable targeting rules, percentage rollout, and target user lists. The SDK sends this context to the server where rules are evaluated securely.

Identify After Authentication

In mobile apps, users typically sign in after the app launches. Use identify to set user context once authentication is complete:

screens/ProfileScreen.tsx

import { useEffect } from 'react';
import { useRollgate } from '@rollgate/sdk-react-native';

function ProfileScreen() {
  const { identify } = useRollgate();

  useEffect(() => {
    if (user) {
      identify({
        id: user.id,
        email: user.email,
        attributes: { plan: user.plan },
      });
    }
  }, [user]);

  return <ProfileContent />;
}

User Context Structure

interface UserContext {
  id: string;           // Required for percentage rollout
  email?: string;       // For email-based targeting
  attributes?: {        // Any custom attributes for targeting rules
    plan?: string;      // e.g., "free", "pro", "growth"
    country?: string;   // e.g., "IT", "US", "DE"
    company?: string;   // e.g., "Acme Inc"
    app_version?: string; // e.g., "2.1.0" (for semver comparisons)
    [key: string]: string | number | boolean;
  };
}

Setting User Context at Startup

If you already know the user at app launch, pass context directly to the provider:

<RollgateProvider
  apiKey="rg_client_..."
  baseUrl="https://api.rollgate.io"
  user={{
    id: 'user-123',
    email: '[email protected]',
    attributes: {
      plan: 'pro',
      country: 'IT',
      company: 'Acme Inc',
      app_version: '2.1.0'
    }
  }}
>
  <Navigation />
</RollgateProvider>

Security: Rules are evaluated server-side. Users cannot see or manipulate the targeting logic - they only receive the final boolean result.

Expo vs Bare React Native

The React Native SDK works with both Expo and bare React Native projects. No native modules are required - the SDK is pure JavaScript.

Expo

Works out of the box with Expo managed and bare workflows. No additional configuration needed.

npx expo install @rollgate/sdk-react-native

Bare React Native

Install via npm or yarn. No native linking required since the SDK is pure JS.

npm install @rollgate/sdk-react-native

Peer dependency: The SDK requires react-native >= 0.70 and react >= 18.

React SDK

Feature flags for React web apps with SSE streaming support

Flutter SDK

Feature flags for Flutter mobile and web applications