The Connect SDK captures visitors' interactions with mobile applications. You can integrate it into your Expo 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 into an Expo managed workflow app for development and testing. For bare React Native, see Integrate the Connect SDK into a React Native 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. Expo SDK 55 or later. Supported React Native versions: 0.82.0–0.85.x. iOS builds require Xcode 26 or later. A development build is required - Expo Go is not supported because the Connect SDK uses Nitro Modules, which require native code that Expo Go cannot load. Use expo-dev-client or EAS Build.

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

• 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. Due to changes introduced in iPadOS 14, the SDK does not support iPad.
• Dual SIM features are in beta. Behavior using multiple carriers may be unreliable.

Initial setup

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

npx expo install expo-dev-client expo-build-properties
npm install react-native-acoustic-connect [email protected]

npx expo install expo-dev-client expo-build-properties
npm install [email protected] [email protected]

2. Open ConnectConfig.json and update the following values with your credentials. All other values are set to safe defaults and do not require changes for initial integration.

3. Add react-native-acoustic-connect and expo-build-properties to your app.json plugins.

{
  "expo": {
    "plugins": [
      "react-native-acoustic-connect",
      ["expo-build-properties", { "android": { "minSdkVersion": 26 } }]
    ]
  }
}

4. Run expo prebuild to generate the native projects.

npx expo prebuild

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

npx acoustic-connect doctor

6. Add the <Connect> wrapper to your app's root component. This is required for screen tracking, touch capture and keyboard event interception.

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>
  )
}

7. Build and run your app.

npx expo run:ios

npx expo run:android

Verify the SDK is running

The SDK auto-initializes at module load using the values from ConnectConfig.json. With "useRelease": false in your config (the default), verbose native logging from Connect, Tealeaf and EOCore is written to the Xcode console (iOS) and Logcat (Android). 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

open -a "Android Studio"

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 - configure APNs (iOS) and FCM (Android) using the bundled Config Plugin.
• Connect React Native SDK public API reference - full method signatures and event types.