The Connect SDK captures visitors' interactions with mobile applications. You can integrate it into your React Native app and track the findings in the Acoustic Connect interface.

Language: TypeScript and JavaScript

Availability: Pro, Premium, and Ultimate

Scope: This guide covers integrating the Connect SDK for development and testing. For Expo, see Integrate the Connect SDK into an Expo app. For production configuration, see Move to production.

Requirements

• Acoustic Connect subscription. You must register your app in Connect and get credentials for it (app key and collector URL). For instructions, see Generate Connect credentials for integration.

• Development environment. Node.js 20 or later. Supported React Native versions: 0.82.0–0.85.x. iOS builds require Xcode 26 or later.

• Peer dependency. react-native-nitro-modules at exactly the version pinned in the SDK's peerDependencies (currently 0.35.9). A version mismatch may cause the SDK to fail at startup — even a patch release can contain breaking changes to the native registration contract. To check your resolved version:

  Shell

  npm ls react-native-nitro-modules

• Mobile app compatibility. iOS 15.1–26.2, Android 8–16 (API 26–36). Android compileSdk 35 or later is required.

Known issues

• Session replay accuracy (iOS). Session replay on iOS may show stale screen snapshots and does not track scroll position. Android is not affected.
• Content inside a WebView component is not captured in session replay.
• iPad is not supported on iOS 14 and later. Due to changes introduced in iPadOS, the SDK does not support iPad on iOS 14 and later.
• Dual SIM features are in beta. Behavior using multiple carriers may be unreliable.

Initial setup

1. From your project root, install the Connect library and its required peer dependency.

npm install react-native-acoustic-connect [email protected]

npm install [email protected] [email protected]

Running the command above automatically creates ConnectConfig.json in your project root. On Android, it also adds the required permissions (INTERNET, ACCESS_NETWORK_STATE, ACCESS_WIFI_STATE, ACCESS_FINE_LOCATION) to AndroidManifest.xml and wires android/app/build.gradle to apply the SDK's config.gradle — no manual manifest edits needed.

2. Open ConnectConfig.json and update the following values with your credentials.

• AppKey — your Connect app key.
• PostMessageUrl — your collector URL.
• KillSwitchUrl — constructed from your collector URL and app key: https://{collector_host}/collector/switch/{app_key}.

All other values in the file are set to safe defaults and do not require changes for initial integration.

3. Install CocoaPods dependencies for iOS.

cd ios && pod install --repo-update

Use --repo-update to ensure CocoaPods fetches the latest pod specs. Omitting it can cause pod resolution failures if your local spec repo is stale. See Troubleshooting > iOS for details.

4. For Android, trigger a Gradle sync in Android Studio. To avoid PATH resolution errors, open Android Studio from a terminal: open -a "Android Studio".

5. Add the <Connect> wrapper to your app's root component (typically App.tsx). This is required for screen tracking, touch capture, and keyboard event interception.

<Connect> wraps your existing JSX — it does not replace your root component structure.

import { NavigationContainer } from '@react-navigation/native'

export default function App() {
  return (
    <NavigationContainer>
      {/* your screens */}
    </NavigationContainer>
  )
}

import { useNavigationContainerRef, NavigationContainer } from '@react-navigation/native'
import { Connect } from 'react-native-acoustic-connect'

export default function App() {
  const navigationRef = useNavigationContainerRef()

  return (
    <Connect
      navigationRef={navigationRef}
      captureKeyboardEvents={true}
    >
      <NavigationContainer ref={navigationRef}>
        {/* your screens */}
      </NavigationContainer>
    </Connect>
  )
}

6. Validate your configuration (recommended).

npx acoustic-connect doctor

doctor checks the things that otherwise fail late and confusingly at build time — Node version and ConnectConfig.json values (AppKey, PostMessageUrl, KillSwitchUrl). It's safe to re-run any time you change ConnectConfig.json.

Verify the SDK is running

Build and run your app. The SDK auto-initializes at module load using the values from ConnectConfig.json. With "useRelease": false in your config (the default), the debug-capable SDK build is available, and verbose native logging from the SDK's native modules — Connect, Tealeaf, and EOCore — can be written to the Xcode console and Logcat. Confirm that the SDK is initializing, capturing screen views, and posting to the collector.

Enable debug logging

Add these environment variables with a value of 1 to your scheme so the Xcode console shows verbose native logging: CONNECT_DEBUG, TLF_DEBUG, and EODebug. Without this step, no verbose native logging appears even with useRelease: false set.

If you have a Connect Ultimate subscription, you can also verify the integration visually: open Behavior studio > Sessions > Session replay and confirm that your session appears and renders correctly.

Troubleshooting

node node_modules/react-native-acoustic-connect/scripts/postinstall.mjs

Next steps

• Identify users at registration — send the account registered signal to associate sessions with contacts in Connect.
• Identify users at sign-in — send the logged in signal to attribute sessions to known contacts.
• Enable push notifications in a React Native app (iOS) — set up APNs with the Connect SDK.
• Move to production — disable verbose logging and prepare your app for release.