On this page
Add CUX to your React Native app, connect navigation and check the data from a test journey. The React Native package delegates collection to native Android and iOS SDKs; it is not the same integration as installing native Android 1.2.0 directly.
Package covered: @cuxio/react-native-sdk 1.0.22.
Requirements
Use a React Native app that can include native modules. An app running only in a client without this native module cannot collect through the bridge.
The package declares React 16.8 or later and React Native 0.64 or later as peer requirements. Those declarations are not a compatibility guarantee for every version or app architecture. Build and test with your actual React Native/toolchain versions.
You also need a CUX mobile project and its token from Settings > Project. On iOS, use an iOS 15 or later deployment target. Check the native dependency resolved by your Android build rather than applying the minimum from the separate Android 1.2.0 guide.
Install the package
Use your existing package manager:
npm install @cuxio/react-native-sdk@1.0.22
Or:
yarn add @cuxio/react-native-sdk@1.0.22
Run pod install for your iOS app, using your project's normal CocoaPods workflow. Rebuild the native app after installation; a JavaScript refresh does not link the native module.
Do not separately replace the wrapper's native dependency with Android 1.2.0. New native APIs need a compatible wrapper before you can use them from JavaScript.
Initialize the SDK
Initialize once from your app's startup path and wait for it to finish before enabling the navigation/event integration:
import { CUX } from '@cuxio/react-native-sdk';
await CUX.initialize({
token: 'YOUR_MOBILE_PROJECT_TOKEN',
debug: false,
needConfirmToStart: true,
});
Place this in your existing async bootstrap, not in a component body that runs on every render. Handle a rejected initialization using your app's startup error handling.
This example waits for your consent handling. Set needConfirmToStart to false only when collection should start immediately. Do not add autoTrackTaps or enableCrashReporting to this example: they are not supported initialization controls in the public implementation covered here.
Choose your next step
| Task | Guide |
|---|---|
| Name the initial screen and connect navigation | Track and name React Native screens |
| Identify an account and record completed outcomes | Identify users and track React Native custom events |
| Handle consent and hide sensitive content | Control React Native collection and mask content |
| Diagnose missing data or integration problems | Troubleshoot your React Native integration |
Verify on both platforms
Build the native Android and iOS apps, initialize, allow collection and run the same test journey. Check the first route, subsequent navigation, interactions, available screenshots and masks.
Test consent withdrawal and account switching. Check events after repeated renders and navigation callbacks. A successful JavaScript call alone does not prove native data delivery.
Connect React Navigation
Connect your existing navigator and name its initial route. Follow the detailed guide.
Understand interaction collection
Check native interaction capture before adding explicit instrumentation. Follow the detailed guide.
Hide sensitive content
Mask sensitive regions before capture. Follow the detailed guide.
Control data collection
Resume or stop collection from your consent handling. Follow the detailed guide.
Identify users
Use a stable internal identifier after login. Follow the detailed guide.
Track custom events
Send an event when your app confirms an outcome. Follow the detailed guide.