SDKs
Help centerCommunityDevelopersAcademyStatus

Integrate the Connect SDK into an Expo app

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.

  • 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. Session replay is best-effort. Some screens, gestures, and navigation events may be missing, duplicated, or shown out of order.
  • Webviews are not captured in session replay. Content rendered inside a WebView component is not recorded.
  • 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.

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

  1. Add the Connect Config Plugin to your app.json.
{
  "expo": {
    "plugins": [
      "react-native-acoustic-connect"
    ]
  }
}

The Config Plugin wires ConnectConfig.json into the Android build at prebuild time so your credentials reach the native assets. Without it, the Android SDK uses placeholder credentials and reports to the wrong collector.

  1. Run expo prebuild to generate the native projects.
npx expo prebuild
⚠️

Warning

The values in ConnectConfig.json are baked into the native bundles at build time, not read at runtime. If you edit the file later, run expo prebuild again before rebuilding.

  1. Add the <Connect> wrapper to your app's root component. This is required for screen tracking, touch capture, and keyboard event interception.
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>
  )
}
  1. Build and run your app to verify the integration.
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.

📘

Note

On Android, filter Logcat by the tags Tealeaf, EOCore, and Connect to isolate SDK output.

Next steps