Add useNavigationContainerRef to your existing @react-navigation/native import. If NavigationContainer is not already imported in this file, add it too. Then add the Connect import and update your component as shown below.

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

Pass navigationRef from useNavigationContainerRef() as an explicit prop to both <Connect> and <NavigationContainer>.

Use this approach if your app uses a different navigation library or no navigation library at all. Import the SDK's default export and call setCurrentScreenName from each screen component.

import AcousticConnectRN from 'react-native-acoustic-connect'

function HomeScreen() {
  AcousticConnectRN.setCurrentScreenName('HomeScreen')
  // ...
}

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.

Verbose logging is on by default — no equivalent setup step needed. Filter Logcat by the tags Tealeaf, EOCore, and Connect to isolate SDK output. To reduce or disable it, set DisplayLogging and LoggingLevel under the Connect object in ConnectConfig.json, then trigger a Gradle sync.

npm install peer-dependency conflict on react-native-nitro-modules

The SDK pins react-native-nitro-modules to an exact version. If npm install reports a peer conflict, your project is resolving a different version. Check the resolved version with npm ls react-native-nitro-modules and align it to the version declared in the SDK's peerDependencies. See Requirements above.

Using --legacy-peer-deps or --force silences the error but does not resolve the underlying mismatch; a version conflict can cause the SDK to fail at startup.

ConnectConfig.json not created after npm install

The file is created by a postinstall script that only runs when npm actually installs packages. If the SDK was already listed in package.json before you ran npm install, npm may skip the script with an "up to date" message. To create the file manually, run:

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

pod install fails with [Connect] requires AcousticConnect >= 2.0.5

You have an older iOS pod version pinned in ConnectConfig.json. Set "iOSVersion" to an empty string to use the latest available version, then re-run pod install --repo-update.

pod install fails with CocoaPods could not find compatible versions

Your local CocoaPods spec repo is stale. Always run pod install --repo-update rather than pod install to ensure the latest pod specs are fetched.

Connect: navigation tracking disabled — no usable NavigationContainer ref resolved

This warning may appear at startup when NavigationContainer is nested inside other providers rather than being a direct child of <Connect>. Screen tracking works correctly despite the warning — it does not indicate a loss of functionality.

pod install fails with [Xcodeproj] Unable to find compatibility version string for object version 'N'

The xcodeproj gem does not yet support the project format version used by your installed Xcode. This can occur any time Xcode ships a new format version before the xcodeproj gem has been updated to match — including between minor Xcode updates.

First, check whether a compatible version of the gem is now available:

gem update xcodeproj
pod install --repo-update

If the gem has not been updated yet, build xcodeproj from source as a temporary workaround:

git clone https://github.com/CocoaPods/Xcodeproj.git /tmp/xcodeproj
cd /tmp/xcodeproj
gem build xcodeproj.gemspec
gem install xcodeproj-*.gem --local

Then re-run pod install --repo-update. Once CocoaPods publishes a compatible gem release, revert to the released version with gem update xcodeproj.

Gradle fails to resolve io.github.go-acoustic:connect

The SDK requires an Android Connect artifact in the range [11.0.11, 12.0.0). If Gradle rejects your pinned version, set "AndroidVersion" in ConnectConfig.json to an empty string and re-sync.

Gradle cannot find node or npx

This occurs when Gradle is launched outside a shell where your Node installation is active — most commonly when Android Studio is opened from the Dock rather than from a terminal.

Recommended fix: Open Android Studio from a terminal so it inherits your shell's PATH:

open -a "Android Studio"

Then re-trigger the Gradle sync. If you need to run ./gradlew clean from the terminal directly, prefix the command with the PATH fix:

PATH="/usr/local/bin:$PATH" ./gradlew clean

Alternative: Create symlinks so Gradle can resolve both binaries from a stable system path regardless of how Android Studio is launched. Use the path that matches your machine:

sudo ln -sf "$(which node)" /opt/homebrew/bin/node
sudo ln -sf "$(which npx)" /opt/homebrew/bin/npx

sudo ln -sf "$(which node)" /usr/local/bin/node
sudo ln -sf "$(which npx)" /usr/local/bin/npx

Verify that the symlink targets exist before running these commands — if which npx resolves to a broken symlink, the commands above will not fix the issue.

Manifest merger failed: minSdkVersion too low

The React Native template sets minSdkVersion 24 by default, which is below the Connect SDK's minimum of API 26. The build fails with:

Manifest merger failed : uses-sdk:minSdkVersion 24 cannot be smaller than version 26
declared in library [io.github.go-acoustic:connect:...]

In android/build.gradle, set minSdkVersion to at least 26:

minSdkVersion = 26

SDK initializes but no session appears in Connect

The kill switch may be returning "die". Check the native log for KillSwitch Responded with 0 and killswitch : says die. The most likely cause is that PostMessageUrl points to a different collector node than the one where your app is registered. Verify the collector URL in your Connect account and update PostMessageUrl in ConnectConfig.json to match, then run pod install --repo-update on iOS (and Gradle sync on Android) and rebuild.