React Native and Expo guide

The React Native SDK is not a separate package. It is the @contentflow/sdk/react-native entry point of the same JavaScript SDK that serves Web and React, so one archive covers every JavaScript platform. The SDK is plain JavaScript with no native module of its own: the native code in your app comes from the packages listed under Dependencies, whose versions you choose.

This page covers which React Native and Expo versions work, how to set each one up, and what behaves differently from the web. The API itself (identity, consent, blocks, campaigns, events) is the same on every platform and is documented in the JavaScript SDK reference.

Compatibility at a glance

Why the line falls there: the SDK publishes its entry points (/react-native, /expo, /react, …) through the exports map in its package.json. Metro, the React Native bundler, only reads that map by default from Metro 0.82, which ships with React Native 0.79 and Expo SDK 53. React Native 0.72 to 0.78 can read it when you opt in. Earlier Metro releases cannot read it at all, and the import fails with Unable to resolve module @contentflow/sdk/react-native.

The rest of the platform requirements are the same for every supported version:

The React Native sample in the release (examples/react-native-app) is built and checked with Expo SDK 57, React Native 0.86 and React 19.2 for each release. The Metro behaviour above was checked by bundling an app on React Native 0.72.17 with and without the setting.

Dependencies

The SDK lists these as optional peer dependencies. Nothing is bundled into it, so you install the version that fits your React Native release and never get a second copy of React or React Native.

Install

1. Download the SDK archive and its checksum file from Releases and downloads, and verify the archive as described in the JavaScript SDK install steps.
2. Install the archive and AsyncStorage, plus any optional packages you need.

Bare React Native:

npm install ./vendor/contentflow-sdk-<version>.tgz
npm install @react-native-async-storage/async-storage
npm install react-native-sse                      # optional: live updates
npm install @react-native-community/geolocation   # optional: device location
cd ios && pod install && cd ..

Expo:

npm install ./vendor/contentflow-sdk-<version>.tgz
npx expo install @react-native-async-storage/async-storage
npx expo install react-native-sse                 # optional: live updates
npx expo install expo-notifications               # optional: push

3. Configure Metro if your version needs it (next section).
4. Rebuild the native app (npx react-native run-ios / run-android, or npx expo run:ios / run:android for a development build). AsyncStorage adds native code, so a JavaScript reload alone is not enough the first time.

Configure Metro

React Native 0.79+ and Expo SDK 53+

Nothing to do. Package exports are on by default. If your metro.config.js sets resolver.unstable_enablePackageExports = false (some apps added this to work around another library), the SDK import will fail; remove that line or set it to true.

React Native 0.72 to 0.78 (bare)

// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const config = {
  resolver: {
    unstable_enablePackageExports: true,
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

Expo SDK 50 to 52

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);
config.resolver.unstable_enablePackageExports = true;

module.exports = config;

After changing the file, restart Metro with a clean cache: npx react-native start --reset-cache, or npx expo start -c.

This setting applies to every package in the app, not only ContentFlow. It is the same behaviour React Native turned on for everyone in 0.79, so most libraries are ready for it, but run through your app once after enabling it. If another library breaks, the practical fix is to upgrade that library or React Native itself.

Set up the provider

Wrap your app once in CFProvider. It creates the client, starts it, and disposes it when the provider unmounts.

import EventSource from 'react-native-sse';                     // optional: live updates
import Geolocation from '@react-native-community/geolocation';  // optional: device location
import { CFProvider, CFBanner } from '@contentflow/sdk/react-native';

export default function App() {
  return (
    <CFProvider
      config={{ publicKey: '<workspace-id>_test', locale: 'ar' }}
      eventSource={EventSource}
      geolocation={Geolocation}
    >
      <Home />
    </CFProvider>
  );
}

function Home() {
  return <CFBanner blockKey="home_banner" onPress={(b) => openLink(String(b.get('cta_url') ?? ''))} />;
}

@contentflow/sdk/react-native exports the same hooks as the React entry (useCF, useCFBlock, useCFBlocks, useCFCampaigns, useCFString, useCFTranslations, useCFTheme, useLiveStatus) plus two ready-made components, CFBanner and CFCampaignBanner. Both are optional: pass render to draw a block with your own components, or use the hooks directly.

To configure the platform yourself (for example, a different storage backend), build the client and hand it to the provider:

import { CFClient, CFProvider, createRNPlatform } from '@contentflow/sdk/react-native';

const config = { publicKey: '<workspace-id>_test' };
const client = new CFClient(
  config,
  createRNPlatform({ EventSource, geolocation: Geolocation, storage: myKeychainStorage }),
);

<CFProvider config={config} client={client}>…</CFProvider>;

Push registration with Expo is covered in Expo push. Bare apps register a native APNs/FCM token with client.registerPushWithReceipt({ token, platform: 'ios', provider: 'apns' }) (or 'android' / 'fcm'), as in the SDK guide.

What is different on React Native

• Storage. Data is kept in AsyncStorage instead of localStorage. Pass storage to createRNPlatform to use something else.
• Secure storage is not applied. On the web, enableSecureStorage (on by default) obfuscates consent and segment data. That needs crypto.subtle, which React Native does not provide, so on React Native the SDK detects this and stores those values in plain AsyncStorage. It is obfuscation, not encryption, even on the web. If you need the data protected at rest, supply a storage adapter backed by the iOS Keychain or Android Keystore.
• Request signing and certificate pinning. The optional JavaScript HMAC and pinning flags fail explicitly on every JavaScript platform, React Native included. Leave them off.
• App lifecycle. The SDK listens to AppState: it flushes queued events and pauses live updates when the app goes to the background, and refreshes when it comes back.
• Live updates. With react-native-sse the SDK streams changes. Without it, it polls. useLiveStatus() shows which one is active.
• Location. Without a geolocation module, requestLocation() rejects immediately and startLocationTracking() logs a warning. The OS permission prompt only appears when you call one of them, never at start.
• SDK version header. Requests identify themselves as react-native/<version> in X-CF-SDK-Version, so the server can tell which SDK build and platform is calling.

Upgrading the SDK

1. Download and verify the new archive, then npm install ./vendor/contentflow-sdk-<new-version>.tgz.
2. Read that version's Action needed notes in the changelog.
3. Restart Metro with a clean cache and rebuild the app.

Upgrading React Native itself does not require a new SDK. If you move to React Native 0.79 or Expo SDK 53 or later, you can delete the unstable_enablePackageExports line from metro.config.js.

Troubleshooting

Generated from the ContentFlow repository by sdk-release/scripts/render-docs.mjs. Downloads and checksums are on Releases and downloads. The SDKs are licensed under the ContentFlow SDK License.