Contentful Personalization & Analytics

React Native Reference Implementation

This is a reference implementation for the Optimization React Native SDK and is part of the Contentful Optimization SDK Suite.

What this demonstrates

Use this implementation when you need an end-to-end React Native example for Android and iOS app targets. It demonstrates SDK initialization, optimized entry rendering, interaction tracking, navigation/screen tracking, offline behavior, preview-panel scenarios, and Detox E2E coverage.

CDA locale handling

The app defines one locale in env.config.ts, passes it to the React Native SDK as top-level locale, and passes it directly to Contentful CDA entry fetches. Do not use contentful.js withAllLocales or raw CDA locale=* for entries passed to OptimizedEntry; SDK entry resolution expects direct single-locale fields such as fields.nt_experiences and fields.nt_variants. See Locale handling in the Optimization SDK Suite for the broader locale model and Entry personalization and variant resolution for the entry contract.

Prerequisites

• Node.js 26.12.1, matching the repository's .nvmrc
• pnpm
• JDK 17, Android SDK platform/build tools 37, adb, and at least one configured Android emulator for Android Detox flows. The one-shot runner and Detox can launch a configured emulator; it does not need to be running before you start the flow.
• Xcode 26 or later, CocoaPods, and an iOS Simulator available for iOS Detox flows

Setup

Run all steps from the monorepo root.

1. Install pnpm packages:

   pnpm install
   Copy

2. Build and package SDK tarballs used by this implementation:

   pnpm build:pkgs
   Copy

3. Install implementation dependencies:

   pnpm implementation:run -- react-native-sdk implementation:install
   Copy

4. Create the local .env file if it does not already exist:

   test -f implementations/react-native-sdk/.env || cp implementations/react-native-sdk/.env.example implementations/react-native-sdk/.env
   Copy

   The .env.example values are mock-safe defaults. Android rewrites localhost URLs to the emulator host alias in env.config.ts; iOS Simulator uses the host network directly.

See implementations/react-native-sdk/package.json for more commands.

Running locally

Run these commands from the monorepo root.

1. Start the mock API server:

   pnpm implementation:run -- react-native-sdk serve:mocks
   Copy

2. In another terminal, start Metro:

   pnpm implementation:run -- react-native-sdk start
   Copy

3. In a third terminal, install and launch the Android app or iOS app:

   pnpm implementation:run -- react-native-sdk android
   pnpm implementation:run -- react-native-sdk ios
   Copy

Use the one-shot E2E runner when you need automatic mock server, Metro, Android emulator, adb reverse, build, and cleanup orchestration.

Running E2E tests

Android E2E tests use Detox. Run these commands from the monorepo root.

1. Run the full root setup and E2E wrapper:

   pnpm setup:e2e:react-native-sdk
   pnpm test:e2e:react-native-sdk
   Copy

2. Run the preferred targeted local Android E2E flow:

   pnpm implementation:run -- react-native-sdk test:e2e:android:full
   Copy

3. Build Android Detox binaries:

   pnpm implementation:run -- react-native-sdk test:e2e:android:build
   Copy

4. Run Android Detox tests only:

   pnpm implementation:run -- react-native-sdk test:e2e:android:run
   Copy

5. Pass script arguments through to the one-shot runner:

   pnpm implementation:run -- react-native-sdk test:e2e:android:full -- --test-file e2e/offline-behavior.test.js
   Copy

   The one-shot Android command:

   • creates .env from .env.example for E2E
   • starts the mock server and Metro
   • configures adb reverse
   • builds the Android app (unless skipped)
   • runs Detox tests
   • cleans up background processes

6. Useful one-shot variants:

   Skip rebuild if the app is already built:

   SKIP_BUILD=true pnpm implementation:run -- react-native-sdk test:e2e:android:full
   Copy

   Run one test file:

   pnpm implementation:run -- react-native-sdk test:e2e:android:full -- --test-file e2e/offline-behavior.test.js
   Copy

   Run tests matching a name pattern:

   pnpm implementation:run -- react-native-sdk test:e2e:android:full -- -t "should recover gracefully when network is restored"
   Copy

7. Run iOS Detox commands when needed:

   pnpm implementation:run -- react-native-sdk test:e2e:ios:build
   pnpm implementation:run -- react-native-sdk test:e2e:ios:run
   Copy

Increasing E2E logging

Local Android E2E logging is intentionally minimal by default.

1. Enable script/service logs (Metro, mock server, and adb logcat stream):

   STREAM_BACKGROUND_LOGS=true ENABLE_DEVICE_LOGCAT=true METRO_VERBOSE=true pnpm implementation:run -- react-native-sdk test:e2e:android:full
   Copy

2. Increase Detox runner logging and artifacts:

   pnpm --dir implementations/react-native-sdk --ignore-workspace exec detox test --configuration android.emu.debug --loglevel trace --record-logs all --take-screenshots failing --record-videos failing
   Copy

3. Read generated logs:

   • implementations/react-native-sdk/logs/mock-server.log
   • implementations/react-native-sdk/logs/metro.log
   • implementations/react-native-sdk/logs/device.log
   • implementations/react-native-sdk/logs/test-results.log

Upgrading React Native

Treat React Native and its associated tooling as one upgrade. Renovate groups the implementation's React Native dependencies and native build tools into a reviewed PR with automerge disabled. The group collects available updates; it does not select compatible versions or migrate native project files.

1. Compare the installed and target React Native releases with the Upgrade Helper and the target release's community template. Update the runtime, Babel preset, Codegen, Gradle plugin, Metro config, and Jest preset together. Select compatible React, test renderer, CLI, and native library versions from the target release's requirements.
2. Apply the required Android and iOS project changes, including Gradle, Kotlin, Android SDK, and Xcode requirements. Preserve the implementation's SDK integration and Detox configuration.
3. Install through pnpm implementation:run -- react-native-sdk implementation:install. The implementation uses the repository's generated SDK tarballs and does not track a pnpm lockfile. Hermes compiler selection belongs to React Native; the implementation hoists that dependency for the Gradle plugin instead of pinning it independently.
4. Refresh iOS pods from implementations/react-native-sdk with bundle install and bundle exec pod update --no-repo-update --project-directory=ios. Review the generated ios/Podfile.lock for changes outside the upgrade and include it with the native project changes.
5. Run the implementation's lint and typecheck commands, Android and iOS release builds, and the maintained Detox flows before merging. Use test:e2e:android:build:release for Android and the ios.sim.release Detox configuration for iOS. Verify navigation, tracking, offline behavior, and the preview panel; a successful dependency install alone does not establish compatibility.

Related

• @contentful/optimization-react-native - React Native SDK package
• React Native SDK package-local dev dashboard - Interactive development harness
• Mock server - HTTP composition for local development and reference implementations
• Mocks package - Shared handlers and fixtures