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.

Prerequisites

• Node.js >= 20.19.0 (24.13.0 recommended to match .nvmrc)
• pnpm 10.x
• An Android emulator available and running for Android Detox flows
• Xcode with 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

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

Running E2E tests

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

1. Run the full Android E2E flow:

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

2. Build Android Detox binaries:

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

3. Run Android Detox tests only:

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

4. 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

5. 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

6. 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

Related

• @contentful/optimization-react-native - React Native SDK package
• React Native SDK package-local dev dashboard - Interactive development harness
• Mocks package - Shared mock API server and fixtures