React Native SDK

1Installation#

# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/

# 2. Install
npm install @abrova/flags-react-native @react-native-async-storage/async-storage
cd ios && pod install

@react-native-async-storage/async-storage stores the anonymous id and the last values. Without it the SDK still works, but keeps them in memory only and logs a warning.

2Provider and hooks#

Wrap your app in AbrovaFlagsProvider. It creates the client, initialises it and closes it when the provider unmounts. Use your public API key (ab_live_...).

import React from 'react';
import { AbrovaFlagsProvider } from '@abrova/flags-react-native';

export default function App() {
  return (
    <AbrovaFlagsProvider config={{ apiKey: 'ab_live_xxx', environment: 'production' }}>
      <Checkout />
    </AbrovaFlagsProvider>
  );
}

Read flags with the hooks. A component that uses a hook re-renders when the values change.

import { useAbrovaFlags, useStringFlag } from '@abrova/flags-react-native';

function Checkout() {
  const { isReady, isEnabled, getNumber } = useAbrovaFlags();
  const theme = useStringFlag('theme', 'light');

  if (!isReady) return <Loading />;

  return isEnabled('new-checkout')
    ? <NewCheckout theme={theme} maxItems={getNumber('max-items', 10)} />
    : <OldCheckout />;
}

The functions returned by useAbrovaFlags() are bound to the client, so you can destructure them. If you created the client yourself, pass it with client instead of config; the provider then leaves init() and close() to you.

3Direct Usage#

You can use the client without React.

import { AbrovaFlags } from '@abrova/flags-react-native';

const flags = new AbrovaFlags({ apiKey: 'ab_live_xxx', environment: 'production' });
await flags.init();

if (flags.isEnabled('new-checkout')) {
  // Show the new checkout
}

const dark = flags.getBoolean('dark-mode', false);
const theme = flags.getString('theme', 'light');
const maxItems = flags.getNumber('max-items', 10);
const layout = flags.getJson('home-layout', { columns: 2 });

init() serves the values cached on the device right away and waits up to initTimeoutMs (5 seconds) for the first answer from the network. After init(), the client is also available as AbrovaFlags.instance.

Getters are synchronous and never throw. Each one takes the default to use when the flag is unknown, when no values are available yet, or when the flag has another type.

Details and reasons

const d = flags.getStringDetail('theme', 'light');
// { value, enabled, variant, reason, version }

getBooleanDetail, getStringDetail, getNumberDetail and getJsonDetail check the flag type. getDetail(key, defaultValue) returns the stored value without a type check, and getAll() returns every value held.

isEnabled is true only for ON and VARIANT.

4Identify the user#

Tell the SDK who the user is and what you know about them. Targeting rules and percentage rollouts are evaluated against this context.

// After sign-in
await flags.identify('user-123', { plan: 'pro', country: 'IR', beta: true });

// Replace all attributes
await flags.setAttributes({ plan: 'business' });

// Signed out, attributes stay
await flags.setUserId(null);

// Sign-out: clears the user id, the attributes and the cached values
await flags.reset();

In a component, call identify in an effect so it runs only when the user changes. Use client from the hook in the dependency list: it stays the same between renders, while the functions returned by the hook are created again when values change.

import { useEffect } from 'react';
import { useAbrovaFlags } from '@abrova/flags-react-native';

function Session({ userId, plan }: { userId: string | null; plan: string }) {
  const { client } = useAbrovaFlags();

  useEffect(() => {
    client.identify(userId, { plan }); // null means signed out
  }, [client, userId, plan]);

  return null;
}

• Each change fetches new values after a short pause (250 ms), so several calls in a row send one request.
• setAttributes and the attributes of identify replace the whole set. They do not merge.
• When the user id changes, the previous user's values are dropped at once. Until the new values arrive, getters return your defaults (reason NOT_READY).
• Attributes are strings, numbers, booleans, null, or arrays of those. No nested objects. At most 100 attributes; a string holds at most 1,024 characters.

If you already know the user at start, pass userId and attributes in the config. The SDK then serves that user's cached values immediately and sends one request instead of two.

Anonymous id

Every install gets a random anonymous id (a UUID). It is stored on the device and sent with every request, so a 10% rollout reaches about 10% of signed-out installs too. When a user id is set, rollouts use the user id instead.

The anonymous id survives reset(). resetAnonymousId() replaces it. Read it with flags.anonymousId.

5Updates and refresh#

// New values arrived
const unsubscribe = flags.subscribe(() => console.log('flags changed'));

// A request failed
const off = flags.onError((e) => console.log(e.statusCode, e.code, e.message));

// Fetch now
await flags.refresh();

The SDK fetches values:

• on init(),
• after identify, setUserId, setAttributes, reset and resetAnonymousId,
• when the app returns to the foreground and the last fetch is older than 15 minutes,
• on refresh(),
• on a timer, only if you set refreshIntervalSeconds.

6Offline and errors#

The last values are stored with AsyncStorage and served at the next start, before the network answers. A failed request never clears them.

• Offline or server error: the last values keep being served. The SDK retries with a growing delay (up to 5 minutes).
• Rate limited (429): the SDK waits the time the service asks for, then retries.
• 401, 403 or 404 (wrong key, Flags not enabled for the project, unknown environment): automatic fetches stop until you call refresh() or restart the app. Check flags.lastError.
• Before the first values: flags.isReady is false and getters return your defaults. await flags.whenReady() resolves when values are available.

flags.close() stops timers and network work.

Configuration Options#

Testing#

Pass an in-memory store, your own fetch and observeAppState: false:

import { AbrovaFlags, MemoryFlagsStorage } from '@abrova/flags-react-native';

const flags = new AbrovaFlags({
  apiKey: 'ab_live_xxx',
  storage: new MemoryFlagsStorage(),
  fetch: mockFetch,
  observeAppState: false,
});

Upgrading from 0.1.x#

0.2.0 is a new API, and 0.1.x clients stop receiving flags. Update the package and change these calls:

Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

Best Practices#