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 a breakdown of how it works:

• 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 (CDA) 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="4ib0hsHWoSOnCVdDkizE8d">
   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 the baseline entry whose ID you copied from Contentful, then attach it 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. Find them in the Contentful web app under Apps → Installed apps → Contentful Personalization → SDK keys.

  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.

Set api.preflight = true only for dry-run Experience API requests that aggregate a fresh profile state on the server without persisting it, for example when validating configuration or exercising targeting rules from a debug tool. It changes Experience delivery for the whole SDK instance, so leave it off in normal application builds.

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.

OptimizationRoot snapshots its config (including defaults, allowedEventTypes, contentful, api, queuePolicy, getAnonymousId, onStatesReady, and trackEntryInteraction) on first render; only locale reacts live and calls sdk.setLocale(...) when the prop changes. Reassigning defaults after mount has no effect — use optimization.consent(...) from useOptimization() for runtime consent changes, and change the provider’s React key to force full re-initialization. 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="4ib0hsHWoSOnCVdDkizE8d">
15
    {(resolvedEntry) => <HeroCard entry={resolvedEntry} />}
16
  </OptimizedEntry>
17
</OptimizationRoot>

For a content-type/slug source, put the descriptor under managedEntry. Inside it, slugField defaults to slug and entryQuery is optional. Use this form when navigation provides an app-owned slug instead of a Contentful entry ID:

Follow this pattern: EntryLoading, EntryError, HeroCard, and their props belong to your app.

1
<OptimizedEntry
2
  managedEntry={{
3
    contentType: 'page',
4
    slug: 'home',
5
    entryQuery: { locale: APP_LOCALE },
6
  }}
7
  loadingFallback={<EntryLoading />}
8
  errorFallback={(error) => <EntryError message={error.message} />}
9
>
10
  {(resolvedEntry) => <HeroCard entry={resolvedEntry} />}
11
</OptimizedEntry>

The SDK merges the managed query, then enforces content_type, fields.<slugField>, and limit: 2. The placeholders below are replaced with the source’s actual content type, effective slug field, and slug:

• No match: Contentful entry not found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".
• More than one match: Multiple Contentful entries found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".

Resolution callbacks, metadata, view tracking, and tap tracking use the fetched entry’s real sys.id, not the slug.

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('4ib0hsHWoSOnCVdDkizE8d', {
2
  include: 10,
3
  locale: APP_LOCALE,
4
})

Every entry passed to OptimizedEntry, useOptimizedEntry, or useEntryResolver().resolveEntry must be a standard contentful.js CDA entry with a top-level metadata object (tags and concepts) — the resolver reads it alongside sys and fields. If your app hand-builds an entry payload (fixtures, cache snapshots, GraphQL responses), or fetches a shape that omits metadata, the resolver silently returns the baseline entry with no error. That is indistinguishable from an entry that has no experience configured, so mapping bugs surface as “personalization isn’t working” with nothing to trace. Pass entries straight from contentfulClient.getEntry(...) when possible; if you must build the payload yourself, include metadata: { tags: [], concepts: [] } at minimum.

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, { entryId, entryQuery? }, or { contentType, slug, slugField?, entryQuery? } source objects. Slug sources with the same content type, slug, effective slug field, locale, include depth, and other effective query values share the managed cache; each different source uses its own getEntries() request. The provider keeps rendering children while the cache warms. React Native does not expose server-to-client managed-entry snapshots 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.

isEmptyVariant === true marks the SDK renderer’s no-content state. It differs from a fallback, which renders the baseline entry. In the no-content state, OptimizedEntry keeps its tracking View, tracking hooks, and onEntryResolved callback active but does not invoke or render your app’s children. Live updates remove existing app content when a result becomes empty and restore it when a later result is not empty. An absent empty-variant flag renders normally. With no measurable or interactive child, the tracking View does not guarantee a view or tap event.

The entry source is a discriminated union: pass baselineEntry (manual fetch), entryId plus optional entryQuery (managed ID fetch), or a content-type/slug descriptor under managedEntry, never more than one source.

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 managedEntry={{ contentType, slug, slugField?, entryQuery? }} when the SDK must look up the entry by a route slug; add slugField only when the Contentful field is not slug.
3. Pass baselineEntry when your application already fetched the entry and must keep manual request ownership.
4. Use loadingFallback, errorFallback, and onEntryError when the managed fetch needs visible loading or error handling.
5. 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.
6. Use static children only when you need entry tracking but not variant data in the child.
7. Use useOptimizedEntry() for the same managed or manual source model without the wrapper component. For example, use useOptimizedEntry({ managedEntry: { contentType: 'page', slug: routeSlug } }) for a slug source.
8. Use useEntryResolver() when a component needs manual-only resolution helpers.

A Contentful entry skeleton is a TypeScript description of one content type and its fields. Use one skeleton union, S, containing every possible baseline or variant content type. Manual OptimizedEntry and useOptimizedEntry() calls, plus the manual useEntryResolver() helpers, use <S, M, L>, where M is the contentful.js response mode and L is the locale. Managed ID and slug component and hook calls use <S, L> because M is fixed to undefined. When every variant shares the baseline content type, omit the generic and let TypeScript infer that skeleton from baselineEntry.

Adapt this to your use case: declare the complete skeleton union and narrow inside the render prop, where the resolved entry becomes native UI. The guard compares sys.contentType.sys.id; it does not validate the entry’s fields.

1
import { OptimizedEntry } from '@contentful/optimization-react-native'
2
import { isEntryOfContentType } from '@contentful/optimization-react-native/api-schemas'
3
import type { Entry, EntryFieldTypes, EntrySkeletonType } from 'contentful'
4
import { Text } from 'react-native'
5
6
type PageSkeleton = EntrySkeletonType<{ title: EntryFieldTypes.Symbol }, 'page'>
7
type HeroSkeleton = EntrySkeletonType<{ headline: EntryFieldTypes.Symbol }, 'hero'>
8
type CtaSkeleton = EntrySkeletonType<{ label: EntryFieldTypes.Symbol }, 'cta'>
9
type AppEntrySkeleton = PageSkeleton | HeroSkeleton | CtaSkeleton
10
type AppLocale = 'en-US'
11
type PageEntry = Entry<PageSkeleton, undefined, AppLocale>
12
13
function PersonalizedPage({ baselineEntry }: { baselineEntry: PageEntry }) {
14
  return (
15
    <OptimizedEntry<AppEntrySkeleton, undefined, AppLocale> baselineEntry={baselineEntry}>
16
      {(entry) => {
17
        if (isEntryOfContentType<HeroSkeleton, undefined, AppLocale>(entry, 'hero')) {
18
          return <Text>{entry.fields.headline}</Text>
19
        }
20
        if (isEntryOfContentType<CtaSkeleton, undefined, AppLocale>(entry, 'cta')) {
21
          return <Text>{entry.fields.label}</Text>
22
        }
23
        return <Text>{entry.fields.title}</Text>
24
      }}
25
    </OptimizedEntry>
26
  )
27
}

The same S flows through hook results, render props, metadata, onEntryResolved, and onTap. Narrow at each renderer or callback boundary before reading content-type-specific fields. The hook result always includes resolvedData, while its top-level entry can be undefined during managed fetching. Gate consumer rendering on isPresentationReady; once ready, omit entry when resolvedData.isEmptyVariant === true. useEntryResolver() uses the current selected optimizations when its second argument is omitted; pass a selection array only when you need an explicit override. The entry model is compile-time only and does not change runtime variant selection.

For a manual render decision, use resolveEntryData() or resolveOptimizedEntry() from useEntryResolver(). Both return the full result, whose isEmptyVariant field tells the app to omit content while retaining the baseline entry for tracking context. The entry-only resolveEntry() convenience cannot distinguish an empty variant.

Follow this pattern: manual resolution with the full result. ResolvedEntryContent is your app-owned renderer.

1
import { useEntryResolver } from '@contentful/optimization-react-native'
2
3
function ManuallyResolvedPage({ baselineEntry }) {
4
  const { resolveEntryData } = useEntryResolver()
5
  const result = resolveEntryData(baselineEntry)
6
7
  return result.isEmptyVariant ? null : <ResolvedEntryContent entry={result.entry} />
8
}

For lower-level resolution and open-ended models, see TypeScript content-model choices.

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, an all-locale payload, or an entry missing top-level metadata, the render prop receives the baseline (original) entry and the UI does not break. A managed-fetch failure is different: when an ID or slug fetch rejects, there is no entry to resolve, so onEntryError fires once and OptimizedEntry renders errorFallback instead of the render prop. While a managed 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.

The render prop and onEntryResolved callback receive a second metadata argument (OptimizedEntryMetadata) alongside the resolved entry. It exposes baselineEntry, baselineEntryId, entry, entryId, selectedOptimization, selectedOptimizations, resolvedData, and optimizationContextId — an opaque runtime-owned identifier that keys any view or tap events your app emits itself to the resolved optimization. useOptimizedEntry() exposes the same shape through its metadata field. You only need optimizationContextId when driving interaction tracking manually instead of through OptimizedEntry’s built-in view and tap tracking.

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.initialize(...) 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.

Every flag read is a tracked analytics exposure, not only subscriptions. optimization.getFlag(name) emits a component flag-view event on every call, and optimization.states.flag(name) emits one per delivered value — once on subscribe (or the first .current read) and again each time the delivered value changes. Deliveries are deduped by (value, componentId, experienceId, variantIndex, profileId) so the same value for the same context is not re-emitted, but the tracking attempt is unconditional. Apply the same governance to flag reads that you apply to other SDK events.

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 runtime ownership

Integration category: Advanced or production-only

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

1. Initialize the SDK with await ContentfulOptimization.initialize(config). initialize is async and returns a Promise<ContentfulOptimization> because it reads AsyncStorage before constructing the single React Native runtime. It is not an isolation context.
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 initialized.
5. Do not create a second active React Native SDK instance without destroying the first one: initialize 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.initialize({
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. This overrides the default ['identify', 'screen'] allow-list, so the Quick Start’s useScreenTracking screen event is silently blocked until consent(true) runs; the block only surfaces through onEventBlocked or states.blockedEventStream. Pair it with a consent flow that resolves before any screen or identify path can run, or accept that pre-consent screen and identify events will be dropped.
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.