Integrate the Optimization React Native SDK in a React Native app

Overview

Use this guide to add Contentful personalization to a React Native or Expo app using @contentful/optimization-react-native. By the end of the quick start, one Contentful entry will render the personalized variant for the current visitor — or the original entry when none applies — and one screen event will report the visitor’s screen view to Contentful, which uses it to keep that visitor’s personalization consistent.

New to personalization? Here is the whole idea in five points:

• In Contentful you author variants of an entry and attach them to an experience — a rule that decides which visitors see which variant.
• As the app runs, Contentful’s Experience API looks at who the visitor is and picks the variant for each experience. Swapping a fetched entry for its picked variant is called resolving the entry.
• The Experience API also returns a profile: the anonymous, per-visitor identity and state used to keep personalization consistent across requests or app launches.
• Your app hands a Contentful entry to the SDK at the point where that entry becomes output. The SDK gives back the selected variant, or the original entry when no variant applies—the baseline fallback. You can fetch the entry yourself or give the SDK your Contentful client and an entry ID; either way, the client stays yours.
• You render the returned entry with the same application components you already use.

The React Native SDK persists the profile across app launches when persistence consent allows it.

That is enough to start. The guide introduces policy and optional capabilities at the point you need them.

You will get there in two milestones:

• Milestone 1 — one entry resolving and one screen event (the quick start below). A single screen mounts OptimizedEntry, which renders the resolved variant or the baseline, and reports one screen event. This is complete and shippable on its own.
• Milestone 2 — the opt-in layers (later). Consent handoff, interaction tracking, identity, live updates, the preview panel, offline delivery, and analytics forwarding, each introduced by the section that needs it.

This guide uses @contentful/optimization-react-native. You mount one OptimizationRoot around your app; it creates the SDK instance, restores state from AsyncStorage, and provides it to the hooks and components below it. Your app still owns its Contentful Delivery API client, locale policy, consent policy, identity policy, navigation, and final rendering.

Quick start

Most React Native + Contentful apps share one shape: a screen fetches or receives a Contentful entry, and somewhere in that screen the entry becomes a rendered component. This quick start assumes that shape and proves the smallest result: one screen renders a resolved entry — variant or baseline — and reports one screen event. It mounts one OptimizationRoot, hands the SDK your Contentful client so it can fetch the entry by ID, and tracks the screen with useScreenTracking.

This quick start assumes your application policy permits Optimization to start with accepted consent and renders no end-user consent UI, so it seeds defaults={{ consent: true }} — the shorthand that accepts both consent axes at once. If personalization must wait for a consent decision, keep this structure and add the Consent and privacy-policy handoff step before you ship, which explains the two axes and the object form that sets them separately.

1. Install the React Native SDK, its required AsyncStorage peer dependency, and a Contentful delivery client if your app does not already have one.

   Copy this:

   1
   pnpm add @contentful/optimization-react-native @react-native-async-storage/async-storage contentful

   AsyncStorage ships native code, so complete your platform’s native install step before launching: run pod install in ios/ for a bare React Native app, or npx expo prebuild (a custom dev build) for Expo, then rebuild the app.

2. Mount OptimizationRoot with your app-owned Contentful client, emit one screen event for profile context, and render one single-locale Contentful entry by ID through OptimizedEntry.

   Adapt this to your use case:

   1
   import { Text } from 'react-native'
   2
   import {
   3
     OptimizationRoot,
   4
     OptimizedEntry,
   5
     useScreenTracking,
   6
   } from '@contentful/optimization-react-native'
   7
   import { createClient } from 'contentful'
   8
   9
   const APP_LOCALE = 'en-US'
   10
   11
   const contentfulClient = createClient({
   12
     accessToken: 'your-contentful-delivery-token',
   13
     environment: 'main',
   14
     space: 'your-space-id',
   15
   })
   16
   17
   function HomeScreen() {
   18
     // Automatic screen tracking uses current-screen dedupe.
   19
     useScreenTracking({ name: 'Home' })
   20
   21
     // OptimizedEntry passes the selected variant or baseline fallback to the renderer.
   22
     return (
   23
       <OptimizedEntry entryId="hero-entry-id">
   24
         {(resolvedEntry) => <Text>{`Resolved entry: ${resolvedEntry.sys.id}`}</Text>}
   25
       </OptimizedEntry>
   26
     )
   27
   }
   28
   29
   export function App() {
   30
     // Use default accepted consent only when your application policy permits it.
   31
     return (
   32
       <OptimizationRoot
   33
         clientId="your-optimization-client-id"
   34
         environment="main"
   35
         locale={APP_LOCALE}
   36
         contentful={{
   37
           client: contentfulClient,
   38
           defaultQuery: {
   39
             // An optimized entry links its experiences and their variants as nested entries; fetch
   40
             // deep enough to pull them back in one payload (see Contentful entry fetching below).
   41
             include: 10,
   42
             locale: APP_LOCALE, // Keep CDA entries and SDK context on the same locale.
   43
           },
   44
         }}
   45
         defaults={{ consent: true }}
   46
         logLevel="debug" // Surface SDK activity, including the accepted screen event, so you can verify it.
   47
       >
   48
         <HomeScreen />
   49
       </OptimizationRoot>
   50
     )
   51
   }

   The App and HomeScreen scaffolding above is illustrative context to match against your own app, not a file to paste over yours. Wrap your existing app root in OptimizationRoot, add useScreenTracking to a screen you already render, and wrap one entry you already render in OptimizedEntry — keep the rest of your components as they are.

3. Verify the first run. Launch the app; the screen displays a resolved entry ID for either the selected variant or the baseline. Because logLevel="debug" is set above, the SDK logs its activity to the console, so you can confirm the screen event fired by watching your Metro or device logs on mount for the screen event the SDK sends (the Screen and navigation tracking and Analytics forwarding sections add states.eventStream for a programmatic check). To see personalization rather than the baseline, author (in Contentful) a variant of hero-entry-id attached to an experience that targets all visitors — every visitor matches it automatically, so the resolved ID changes to the variant. Without an authored variant every launch shows the baseline entry, which is expected, not a failure.

Before you start

The sections below walk the integration in order. First, gather the few things you can only get from outside this guide:

• A React Native or Expo app with React and React Native installed, its own Contentful fetching already working, and the ability to run a native build step (pod install for bare React Native, npx expo prebuild for Expo) — the SDK’s required AsyncStorage peer dependency ships native code.
• Contentful delivery credentials — space ID, delivery token, and environment — read from your app’s runtime configuration.
• At least one entry with a variant attached to an experience, authored in Contentful. Without an authored variant, the integration can still run correctly while returning the baseline, so you cannot yet distinguish working personalization from a content-authoring gap. For the first personalized-content test, target all visitors so the test request or visitor matches automatically.
• Your Optimization project values — client ID and environment, from your Optimization project settings. The Experience API (which picks variants) and the Insights API (which receives event and interaction delivery) each have a base URL that defaults correctly; you only set them for mocks or non-default hosts (see Install and initialize OptimizationRoot).

You do not need a setup inventory up front. Everything else — consent, entry resolution, screen tracking, interaction tracking, identity, live updates, preview, offline delivery — is introduced by the section that needs it.

Core integration

Install and initialize OptimizationRoot

Integration category: Required for first integration

You mounted OptimizationRoot in the quick start; this section covers its full configuration surface — onStatesReady, api host overrides, logLevel, and reading the SDK instance with useOptimization(). OptimizationRoot is the normal React Native entry point: it creates the SDK instance, waits for AsyncStorage-backed state setup, runs onStatesReady when provided, then renders provider children. It also composes live-update and interaction-tracking context for descendant components.

1. Mount one OptimizationRoot around all components that call React Native SDK hooks.
2. Pass clientId from runtime configuration. Pass environment only when you do not use the default Contentful environment; when you omit it the SDK uses main.
3. Pass locale when Experience API responses and event context must use the same app locale as your Contentful entry fetches.
4. Pass api endpoint overrides only for staging, mocks, or non-default production hosts. Both base URLs default correctly otherwise, so most apps omit api entirely.
5. Provide onStatesReady when app-level code must subscribe to SDK state before child effects run (see Analytics forwarding).

Adapt this to your use case:

1
import { OptimizationRoot } from '@contentful/optimization-react-native'
2
import type { ReactNode } from 'react'
3
4
export function AppRoot({ children }: { children: ReactNode }) {
5
  // Override API hosts only for staging, mocks, or non-default production hosts.
6
  return (
7
    <OptimizationRoot
8
      clientId="your-optimization-client-id"
9
      environment="main"
10
      locale="en-US"
11
      api={{
12
        // Set these only for staging, mocks, or non-default hosts; both default correctly otherwise.
13
        experienceBaseUrl: 'https://experience.staging.example.com/',
14
        insightsBaseUrl: 'https://insights.staging.example.com/',
15
      }}
16
      logLevel="warn"
17
    >
18
      {children}
19
    </OptimizationRoot>
20
  )
21
}

Use useOptimization() under the provider when a component needs the SDK instance. The hook throws outside OptimizationRoot or OptimizationProvider, and the provider-owned path withholds children until the SDK is ready.

Consent and privacy-policy handoff

Integration category: Common but policy-dependent

Consent policy belongs to your application. Consent has two independent axes: events (may the SDK personalize and send events) and persistence (may the SDK store profile continuity in AsyncStorage). The shorthand consent: true sets both to true; the object form { events, persistence } sets them separately. The SDK stores event consent, stores separate durable profile-continuity persistence consent, and blocks non-allowed event types until event consent is accepted.

1. If application policy permits Optimization by default and you do not render a user consent UI, seed accepted consent during SDK initialization.
2. If consent depends on user choice, leave defaults.consent unset and call optimization.consent(true | false) from the application-owned banner, CMP callback, or settings flow.
3. Use object-form consent when events are permitted but profile continuity must stay session-only.
4. Configure allowedEventTypes only after privacy review approves which events can emit before consent.
5. Subscribe to states.blockedEventStream during development when you need to verify blocked calls.

Adapt this to your use case:

1
// Use this only when policy allows Optimization to start accepted.
2
<OptimizationRoot clientId="your-optimization-client-id" defaults={{ consent: true }}>
3
  <YourApp />
4
</OptimizationRoot>

Adapt this to your use case:

1
import { Button, View } from 'react-native'
2
import { useOptimization } from '@contentful/optimization-react-native'
3
4
function ConsentControls() {
5
  const optimization = useOptimization()
6
7
  return (
8
    <View>
9
      {/* Boolean consent updates event consent and durable profile-continuity consent together. */}
10
      <Button title="Accept" onPress={() => optimization.consent(true)} />
11
      <Button title="Reject" onPress={() => optimization.consent(false)} />
12
    </View>
13
  )
14
}

By default, React Native permits identify and screen before event consent is accepted. Entry views, entry taps, and any other event type are blocked until consent is accepted or that type is allow-listed. Boolean consent calls control both event emission and durable profile continuity. Use optimization.consent({ events: true, persistence: false }) when events can emit but the stored profile-continuity state must stay session-only. That state is the anonymous identity, the profile, the selected optimizations (which variant the Experience API picked for each experience), and the changes (the profile-backed values the Experience API returns for feature flags — named on/off or valued settings — and merge tags — profile-driven substitutions in Rich Text; both are covered in Merge tags and Custom Flags) — all of which otherwise persist in AsyncStorage across launches.

For cross-SDK policy details, see Consent management in the Optimization SDK Suite.

Contentful entry fetching and locale shape

Integration category: Required for first integration

Your app owns the Contentful client and locale policy. The React Native SDK can call that client when contentful: { client } is configured, or your app can fetch a manual baselineEntry. Both paths must produce a standard single-locale Contentful CDA entry payload where optimized fields are direct values, not locale-keyed maps.

1. Choose the application Contentful locale in your app configuration, i18n layer, or navigation layer.
2. Configure contentful.defaultQuery on the SDK, pass per-entry entryQuery, or pass the locale to manual Contentful CDA requests.
3. Request enough link depth for the SDK to resolve variants. nt_experiences (plural) is a fixed Optimization link field the SDK adds to an optimized entry; it links that entry’s experiences, and each experience links its variant entries. Do not confuse it with nt_experience (singular), the content type of the experience entries it links to. Both are SDK-owned content-model names you do not choose. Your fetch must include deeply enough to pull those linked entries back in one payload. include: 10 is the repository reference implementation’s pattern.
4. Pass the same locale to SDK locale when Experience API responses and event context must use the same language.
5. Do not pass contentful.js withAllLocales results or raw CDA locale=* responses to OptimizedEntry, useOptimizedEntry, or useEntryResolver.
6. Pass prefetchManagedEntries to OptimizationRoot or OptimizationProvider when a screen knows the managed entries it will render soon and you want the SDK to warm its managed-entry cache after readiness.

Adapt this to your use case:

1
const APP_LOCALE = 'en-US'
2
3
<OptimizationRoot
4
  clientId="your-optimization-client-id"
5
  locale={APP_LOCALE}
6
  contentful={{
7
    client: contentfulClient,
8
    defaultQuery: {
9
      include: 10, // Resolve optimization and variant links before SDK resolution.
10
      locale: APP_LOCALE, // Keep CDA entries and SDK context on the same locale.
11
    },
12
  }}
13
>
14
  <OptimizedEntry entryId="hero-entry-id">
15
    {(resolvedEntry) => <HeroCard entry={resolvedEntry} />}
16
  </OptimizedEntry>
17
</OptimizationRoot>

Manual fetching remains supported when your app needs request ownership around one entry:

Adapt this to your use case:

1
const entry = await contentfulClient.getEntry('hero-entry-id', {
2
  include: 10,
3
  locale: APP_LOCALE,
4
})

Changing the provider locale prop after initialization calls sdk.setLocale(nextLocale). After the locale update, Experience API requests and event context use the new locale, but the SDK does not refetch Contentful entries or refresh profile state. Refetch entries and run your normal screen(), identify(), or profile refresh path when localized data must update.

prefetchManagedEntries accepts entry ID strings or { entryId, entryQuery } descriptors. The provider keeps rendering children while the cache warms. React Native does not expose prefetchedManagedEntries because it has no server-to-client hydration handoff path.

For the entry contract, see Entry optimization and variant resolution. For the broader locale model, see Locale handling in the Optimization SDK Suite.

Entry resolution and fallback rendering

Integration category: Required for first integration

OptimizedEntry resolves the selected Contentful variant for the current profile and passes non-optimized entries through unchanged. Invalid, incomplete, or unmatched optimization data falls back to the baseline entry instead of throwing.

The entry source is a discriminated union: pass either entryId (managed fetch) or baselineEntry (manual fetch), never both.

1. Pass entryId to let the SDK fetch the baseline entry through the configured Contentful client (managed fetching, from the Contentful entry fetching and locale shape section).
2. Pass baselineEntry when your application already fetched the entry and must keep manual request ownership.
3. Use loadingFallback, errorFallback, and onEntryError when the managed fetch needs visible loading or error handling.
4. Use a render prop — a function passed as the child, which receives the resolved entry and returns your UI — when the child needs the resolved baseline or variant entry. This is the {(resolvedEntry) => ...} form the quick start used.
5. Use static children only when you need entry tracking but not variant data in the child.
6. Use useOptimizedEntry() for the same managed or manual source model without the wrapper component.
7. Use useEntryResolver() when a component needs manual-only resolution helpers.

Adapt this to your use case:

1
import {
2
  OptimizedEntry,
3
  useEntryResolver,
4
  useOptimizedEntry,
5
} from '@contentful/optimization-react-native'
6
import type { Entry } from 'contentful'
7
8
function HeroSection() {
9
  return (
10
    <OptimizedEntry
11
      entryId="hero-entry-id"
12
      loadingFallback={null}
13
      errorFallback={null}
14
      onEntryError={(error) => diagnostics.report(error)}
15
    >
16
      {(resolvedEntry) => <HeroCard entry={resolvedEntry} />}
17
    </OptimizedEntry>
18
  )
19
}
20
21
function HeroData() {
22
  // isPresentationReady is true once the entry is fetched and resolved and is safe to render.
23
  const { entry, isPresentationReady } = useOptimizedEntry({ entryId: 'hero-entry-id' })
24
25
  if (!isPresentationReady || !entry) return null
26
27
  return <HeroCard entry={entry} />
28
}
29
30
function HeroManualData({ baselineEntry }: { baselineEntry: Entry }) {
31
  const { resolveEntry } = useEntryResolver()
32
  // resolveEntry uses current selected optimizations and falls back to baseline content.
33
  const resolvedEntry = resolveEntry(baselineEntry)
34
35
  return <HeroCard entry={resolvedEntry} />
36
}

When you use the useOptimizedEntry hook directly, isPresentationReady is true once the entry has been fetched (for a managed entryId) and resolved, so the returned entry is safe to render; gate your render on it as the example does. OptimizedEntry handles this for you and only calls the render prop when the entry is ready.

The resolved entry has the same field shape as the baseline entry, handed to the render prop as a base contentful Entry. Cast it to your content-type interface in the child (resolvedEntry as HeroFields) when your renderer needs the narrower type; the plain direct cast works for common narrowed types. Downstream renderers can render the fields without branching on whether the SDK returned a variant.

There are two distinct outcomes, and they use different props. The baseline fallback is a resolution outcome on an entry the SDK already has: on denied consent, no matching variant, unresolved links, or an all-locale payload, the render prop receives the baseline (original) entry and the UI does not break. A managed-fetch failure is different: when entryId is used and the SDK’s fetch rejects, there is no entry to resolve, so onEntryError fires once and OptimizedEntry renders errorFallback instead of the render prop. While a managed entryId fetch is unresolved, OptimizedEntry shows loadingFallback until the fetch settles; there is no time limit on that loading window, so provide a loadingFallback for any entry the reader waits on.

Screen and navigation tracking

Integration category: Required for first integration

Screen events update the mobile profile and route-aware event context. The SDK gives you a React Navigation adapter and two hook paths.

1. Use OptimizationNavigationContainer when your app uses React Navigation and you want automatic events for active route changes.
2. Use useScreenTracking() inside a screen when the app does not use React Navigation or when the event must wait for screen data.
3. Use useScreenTrackingCallback() for imperative tracking when the screen name comes from a deep link, navigation state transform, or another runtime value.
4. Avoid tracking the same route with both the navigation adapter and a screen hook.
5. Set includeParams on OptimizationNavigationContainer only when route params are approved for event payloads. Params are JSON-validated before they are attached.

Adapt this to your use case:

1
import { NavigationContainer } from '@react-navigation/native'
2
import { createNativeStackNavigator } from '@react-navigation/native-stack'
3
import { useEffect } from 'react'
4
import {
5
  OptimizationNavigationContainer,
6
  useScreenTracking,
7
} from '@contentful/optimization-react-native'
8
9
const Stack = createNativeStackNavigator()
10
11
function DetailsScreen({ dataLoaded }: { dataLoaded: boolean }) {
12
  // Disable mount tracking when the screen event must wait for app data.
13
  const { trackScreen } = useScreenTracking({
14
    name: 'Details',
15
    trackOnMount: false,
16
  })
17
18
  useEffect(() => {
19
    if (dataLoaded) {
20
      void trackScreen()
21
    }
22
  }, [dataLoaded, trackScreen])
23
24
  return <DetailsContent />
25
}
26
27
function NavigationShell() {
28
  return (
29
    // Use the navigation adapter as the single automatic route-tracking path.
30
    <OptimizationNavigationContainer>
31
      {(navigationProps) => (
32
        <NavigationContainer {...navigationProps}>
33
          <Stack.Navigator>
34
            <Stack.Screen name="Home" component={HomeScreen} />
35
            <Stack.Screen name="Details" component={DetailsScreen} />
36
          </Stack.Navigator>
37
        </NavigationContainer>
38
      )}
39
    </OptimizationNavigationContainer>
40
  )
41
}

The automatic navigation path uses trackCurrentScreen() for current-screen deduplication. Direct manual screen() calls are still direct event emits.

To verify screen tracking, open one tracked screen and confirm one accepted screen event through SDK logs, states.eventStream, or your approved event inspection path.

Entry interaction tracking

Integration category: Common but policy-dependent

Entry interaction tracking records views and taps for Contentful entries. View and tap tracking are enabled by default on OptimizedEntry.

1. Decide whether entry view and tap events are allowed by your application’s Analytics and privacy policy.
2. Set root defaults with trackEntryInteraction only when most entries need to opt out of a default interaction.
3. Override an individual entry with trackViews, trackTaps, or onTap.
4. Wrap scrollable screens with OptimizationScrollProvider so view tracking uses the actual scroll position.
5. Tune minVisibleRatio, dwellTimeMs, and viewDurationUpdateIntervalMs only when product analytics requirements differ from the defaults.

Adapt this to your use case:

1
<OptimizationRoot clientId="your-optimization-client-id" defaults={{ consent: true }}>
2
  {/* Scroll context lets view tracking use the actual scroll viewport. */}
3
  <OptimizationScrollProvider>
4
    <OptimizedEntry
5
      baselineEntry={entry}
6
      dwellTimeMs={1000}
7
      minVisibleRatio={0.5}
8
      onTap={(resolvedEntry) => {
9
        navigation.navigate('EntryDetail', { id: resolvedEntry.sys.id })
10
      }}
11
    >
12
      {(resolvedEntry) => <EntryCard entry={resolvedEntry} />}
13
    </OptimizedEntry>
14
  </OptimizationScrollProvider>
15
</OptimizationRoot>

The default view threshold is 80% visibility (minVisibleRatio 0.8) for 2000 ms (dwellTimeMs). After the first view event, periodic duration updates emit every 5000 ms (viewDurationUpdateIntervalMs) while the entry remains visible. Without OptimizationScrollProvider, the SDK assumes scrollY is 0 and uses the screen height as the viewport, which is appropriate only for non-scrollable or already-visible layouts.

React Native tracks two interactions: entry views and entry taps (there is no hover). A touch counts as a tap only when the finger moves less than 10 points between touch start and end, so a scroll gesture that starts on an entry does not register as a tap. On the wire, a tap is delivered as a component_click event.

For event timing, scroll context, tap distance, and backgrounding mechanics, see React Native SDK interaction tracking mechanics.

Identity, profile continuity, and reset

Integration category: Common but policy-dependent

Identity policy belongs to your application. The SDK can send known-user traits, maintain profile-continuity state, and reset its in-memory profile state, but it does not decide when a user becomes known or how account data is governed.

1. Call identify({ userId, traits }) after authentication or account state proves the user’s identity.
2. Keep traits limited to values approved for Optimization profile use.
3. Call reset() on sign-out, account switch, or privacy reset flows that must clear SDK profile state.
4. Use object-form consent when profile continuity persistence must differ from event consent.
5. Implement any web, server, or account continuity handoff in application code. React Native uses AsyncStorage and does not provide a built-in browser-cookie handoff.

Adapt this to your use case:

1
import { Button, View } from 'react-native'
2
import { useOptimization } from '@contentful/optimization-react-native'
3
4
function AccountControls() {
5
  const optimization = useOptimization()
6
7
  return (
8
    <View>
9
      <Button
10
        title="Identify"
11
        onPress={() => {
12
          // identify links the app-owned user ID to the current mobile profile.
13
          void optimization.identify({
14
            userId: 'user-123',
15
            traits: { plan: 'pro' },
16
          })
17
        }}
18
      />
19
      <Button title="Reset" onPress={() => optimization.reset()} />
20
    </View>
21
  )
22
}

AsyncStorage persists consent state and, when persistence consent permits it, profile, selected optimizations, changes, and anonymous identity across app launches. It does not persist SDK event queues. Live SDK state after startup comes from in-memory SDK state, not repeated AsyncStorage reads.

For advanced anonymous ID ownership, pass getAnonymousId to OptimizationRoot or ContentfulOptimization.create(...) only when your app owns an approved anonymous ID that Optimization can use. Otherwise, omit it and rely on the React Native SDK’s AsyncStorage-backed anonymous ID default.

Optional integrations

Merge tags and Custom Flags

Integration category: Optional

Use merge tags and Custom Flags when your app renders profile-backed Rich Text values or feature values returned in the Experience API changes data. Entry replacement and flag rendering are separate decisions: OptimizedEntry chooses an entry variant, while flags and merge tags read profile-backed values from SDK state.

1. Resolve merge tags inside your app-owned Rich Text renderer with the SDK instance returned by useOptimization().
2. Subscribe to sdk.states.flag(name) when a component needs to rerender as a flag value changes.
3. Treat flag values and merge-tag values as profile-dependent runtime data, not as static Contentful content.

Adapt this to your use case:

1
import { useEffect, useState } from 'react'
2
import { Text } from 'react-native'
3
import { useOptimization } from '@contentful/optimization-react-native'
4
5
function PromoFlag() {
6
  const optimization = useOptimization()
7
  const [enabled, setEnabled] = useState(false)
8
9
  useEffect(() => {
10
    // Subscribe once per flag value that must rerender as profile state changes.
11
    const subscription = optimization.states.flag('show-promo').subscribe((value) => {
12
      setEnabled(value === true)
13
    })
14
15
    return () => subscription.unsubscribe()
16
  }, [optimization])
17
18
  return enabled ? <Text>Promo</Text> : null
19
}

For the deeper data model, see Entry optimization and variant resolution.

Live updates

Integration category: Optional

By default, OptimizedEntry locks to the first selected variant it receives for that component lifetime. This prevents visible content changes when profile state changes while the user is viewing the entry.

1. Set liveUpdates on OptimizationRoot when all optimized entries in the app can react to profile and variant changes.
2. Set liveUpdates on an individual OptimizedEntry when only one section can update in place.
3. Use useLiveUpdates() only for UI that needs to display or react to the live-update state.
4. Remember that the preview panel forces live updates while it is open.

Adapt this to your use case:

1
<OptimizationRoot clientId="your-optimization-client-id" liveUpdates>
2
  {/* Per-entry false keeps this section locked even when root live updates are enabled. */}
3
  <OptimizedEntry baselineEntry={dashboardEntry} liveUpdates={false}>
4
    {(resolvedEntry) => <Dashboard entry={resolvedEntry} />}
5
  </OptimizedEntry>
6
</OptimizationRoot>

Live-update resolution order is preview panel open, component liveUpdates prop, OptimizationRoot liveUpdates prop, then the default locked behavior.

Preview panel

Integration category: Optional

The preview panel is an in-app authoring and debugging surface. It fetches your audience and experience definitions (nt_audience and nt_experience, the fixed Optimization content types, not names you choose) through the Contentful client you provide, lets users override audiences and variants locally, and forces live updates while the panel is open.

1. Install the preview peer dependencies before importing the preview subpath.
2. Mount PreviewPanelOverlay under OptimizationRoot.
3. Pass a Contentful client that can fetch the space and environment containing Optimization audience and experience entries.
4. Gate the panel behind __DEV__ or an equivalent internal build flag.
5. Provide onRefresh when the panel must trigger a fresh Experience API request after overrides.

Copy this:

1
pnpm add @react-native-clipboard/clipboard react-native-safe-area-context

Adapt this to your use case:

1
import { OptimizationRoot, useOptimization } from '@contentful/optimization-react-native'
2
import { PreviewPanelOverlay } from '@contentful/optimization-react-native/preview'
3
import { createClient } from 'contentful'
4
5
const contentfulClient = createClient({
6
  accessToken: 'your-contentful-delivery-token',
7
  environment: 'main',
8
  space: 'your-space-id',
9
})
10
11
function AppContent() {
12
  const optimization = useOptimization()
13
14
  return (
15
    <>
16
      <YourApp />
17
      {/* Gate preview UI out of production builds. */}
18
      {__DEV__ && (
19
        <PreviewPanelOverlay
20
          contentfulClient={contentfulClient}
21
          onRefresh={() => {
22
            // Re-emit a screen event to refresh selected optimizations after preview overrides.
23
            void optimization.screen({ name: 'Preview Refresh' })
24
          }}
25
        />
26
      )}
27
    </>
28
  )
29
}
30
31
export function App() {
32
  return (
33
    <OptimizationRoot clientId="your-optimization-client-id">
34
      <AppContent />
35
    </OptimizationRoot>
36
  )
37
}

PreviewPanelOverlay must be rendered inside OptimizationRoot, or inside both OptimizationProvider and LiveUpdatesProvider. Expo apps that use preview native modules need a custom dev build, such as expo run:ios or expo run:android; Expo Go is not enough.

Offline event delivery

Integration category: Optional

When @react-native-community/netinfo is installed, the SDK listens for connectivity changes. NetInfo gates flushing while the app is offline and resumes flushing when the device is reachable. Offline replay is in memory while the JavaScript process remains alive; NetInfo does not create a durable event outbox. When NetInfo is absent, the SDK logs a warning and runs without offline detection.

1. Install NetInfo when the app must replay in-memory SDK events after offline periods.
2. Keep queue sizing and drop policy aligned with product Analytics requirements.
3. Verify that app backgrounding flushes queues and drains pending AsyncStorage writes on your supported platforms. AsyncStorage persistence covers consent and profile continuity, not event queues.

Copy this:

1
pnpm add @react-native-community/netinfo

The SDK also listens for React Native AppState transitions to background or inactive and calls flush() before the operating system can suspend the process.

Analytics forwarding

Integration category: Optional

Use Analytics forwarding when your mobile app already sends events to a customer-data platform, product analytics destination, or vendor SDK. The Optimization SDK still sends its own events to Contentful. Your application decides which approved Contentful context can also be forwarded.

1. Attach app-level subscriptions with onStatesReady so subscribers register before child effects can emit screen, entry, or blocked-event updates.
2. Read states.eventStream for SDK events that were accepted.
3. Read states.blockedEventStream to verify consent and allowedEventTypes blocks during development.
4. Dedupe forwarded events by messageId or by destination-specific semantic keys when one user action produces multiple event deliveries.
5. Store forwarded message IDs in module or app state so remounts do not forward the same event again. If the destination must receive only future SDK events, read the current messageId before subscribing and skip that event.
6. Apply the same consent, privacy, and data-minimization policy to forwarded payloads that you apply to first-party SDK events.

Adapt this to your use case:

1
const forwardedMessageIds = new Set<string>()
2
3
<OptimizationRoot
4
  clientId="your-optimization-client-id"
5
  onStatesReady={(states) => {
6
    // Register before child effects emit screen, entry, or flag events.
7
    const initialMessageId = states.eventStream.current?.messageId
8
9
    const subscription = states.eventStream.subscribe((event) => {
10
      if (!event) return
11
      if (forwardedMessageIds.has(event.messageId)) return
12
      if (event.messageId === initialMessageId) {
13
        forwardedMessageIds.add(event.messageId)
14
        return
15
      }
16
      if (!canForwardSdkEvent(event)) return
17
18
      forwardedMessageIds.add(event.messageId)
19
      analytics.track(`Contentful ${event.type}`, pickContentfulEventProperties(event))
20
    })
21
22
    return () => subscription.unsubscribe()
23
  }}
24
>
25
  <YourApp />
26
</OptimizationRoot>

Use Forwarding Optimization SDK context to analytics and tag-management tools for destination mapping, consent, identity, dedupe, and governance guidance.

Advanced integrations

Explicit SDK instance ownership

Integration category: Advanced or production-only

Use explicit instance ownership only when a framework adapter, test harness, or application service must create the SDK before React renders. OptimizationRoot is the preferred path for normal React Native apps.

1. Create the SDK with await ContentfulOptimization.create(config). create is async and returns a Promise<ContentfulOptimization> because it reads AsyncStorage before constructing.
2. Pass the resolved instance to OptimizationProvider sdk={sdk}.
3. Wrap the tree in the exported LiveUpdatesProvider only when preview tooling or global live-update state must work without OptimizationRoot.
4. Call destroy() from the owner during teardown, once the instance is done. OptimizationProvider does not destroy an injected SDK; destroy() clears the singleton so a new instance can be created.
5. Do not create a second active React Native SDK instance without destroying the first one: create throws ContentfulOptimization React Native SDK is already initialized. Reuse the existing instance. while a live instance exists.
6. Use per-entry trackViews and trackTaps for interaction policy in injected-provider flows; trackEntryInteraction is an OptimizationRoot convenience.

Follow this pattern:

1
import { ContentfulOptimization, OptimizationProvider } from '@contentful/optimization-react-native'
2
3
const sdk = await ContentfulOptimization.create({
4
  clientId: 'your-optimization-client-id',
5
  environment: 'main',
6
  locale: 'en-US',
7
})
8
// The owner that creates an injected SDK must call sdk.destroy() during teardown.
9
10
function App() {
11
  return (
12
    <OptimizationProvider sdk={sdk}>
13
      <YourApp />
14
    </OptimizationProvider>
15
  )
16
}

Strict event admission and queue controls

Integration category: Advanced or production-only

Use strict controls when privacy review, regulated deployments, or constrained mobile networks need behavior beyond the default React Native settings.

1. Set allowedEventTypes={[]} when no event can emit before explicit event consent.
2. Use onEventBlocked to surface consent or guard failures in diagnostics.
3. Configure queuePolicy.offlineMaxEvents and queuePolicy.onOfflineDrop when the offline Experience buffer must have explicit bounds and observability.
4. Configure queuePolicy.flush only when flush behavior must differ from SDK defaults across shared Insights and Experience delivery.
5. Use api endpoint overrides and fetchOptions for staging, mocks, and request-level options such as requestTimeout and retries.

Adapt this to your use case:

1
// Empty allow-list means no event emits before explicit consent.
2
<OptimizationRoot
3
  clientId="your-optimization-client-id"
4
  allowedEventTypes={[]}
5
  onEventBlocked={(blocked) => {
6
    // blocked is { reason, method, args }: the blocked method name and its original arguments.
7
    diagnostics.log('Optimization event blocked', blocked.method)
8
  }}
9
  queuePolicy={{
10
    // Bound the offline Experience buffer for constrained mobile networks.
11
    offlineMaxEvents: 50,
12
    onOfflineDrop: ({ droppedCount }) => {
13
      // The callback receives a context object; droppedCount is how many events were dropped.
14
      diagnostics.log('Dropped offline Experience events', { droppedCount })
15
    },
16
  }}
17
  fetchOptions={{
18
    requestTimeout: 3000, // ms before a request times out (default 3000).
19
    retries: 1, // retry attempts on failure (default 1).
20
  }}
21
>
22
  <YourApp />
23
</OptimizationRoot>

Platform build boundaries

Integration category: Advanced or production-only

React Native platform setup determines which optional SDK behavior is available at runtime.

1. Run native install steps for AsyncStorage and any optional native peer dependency you add.
2. Use a custom Expo dev build for preview panel dependencies; Expo Go cannot load the required native modules.
3. Keep preview UI out of production builds with build flags or internal distribution channels.
4. When testing against a local mock server on the Android emulator, rewrite localhost API hosts to the emulator host alias 10.0.2.2 in your own app configuration. The SDK has no localhost rewrite; this is app-config you own. The reference implementation does exactly this in env.config.ts (localhost → 10.0.2.2 on Android; the iOS Simulator uses the host network directly).
5. For release builds, verify that the Contentful CDA host, Experience API host, and Insights API host point to the intended environment.

Production checks

Before release, verify these checks in the app build and environment that will ship:

• Credentials and runtime configuration - The app uses the intended Optimization clientId, Optimization environment, API hosts, Contentful space, Contentful environment, CDA token, and app locale. Android emulator-only localhost rewrites are not present in production configuration.
• Consent behavior - Default accepted consent is used only when policy permits it. User-choice flows call consent(true | false), object-form consent matches the persistence policy, and rejected consent blocks non-allowed event types.
• Event delivery - Screen, identify, entry view, entry tap, Custom Flag, and forwarded Analytics events appear in the expected destinations. In-memory offline replay and background flushing are verified when NetInfo is installed.
• Content fallback behavior - Optimized entries are fetched with one CDA locale and enough link depth. Non-optimized, unmatched, or incomplete entries render baseline content instead of blank UI.
• Duplicate tracking prevention - One OptimizationRoot owns the app runtime, each route uses one screen-tracking path, and the app does not wrap the same rendered entry multiple times for one impression. Forwarded events are deduped before leaving the app.
• Privacy and governance - Forwarded Analytics payloads are allow-listed, profile traits are approved, preview UI is absent from production builds, and persisted profile continuity matches consent records.
• Local validation path - Compare behavior against the React Native reference implementation and run the smallest meaningful app validation for the changed flow, such as typecheck, lint, or a targeted Detox file through the repository runner.

Troubleshooting

Reference implementations to compare against

• React Native reference implementation - The in-tree React Native app that demonstrates provider setup, consent bootstrap, CDA locale handling, optimized entry rendering, scroll provider usage, tap tracking, navigation tracking, live updates, preview panel behavior, offline behavior, and Detox E2E coverage.