The Connect SDK for React Native is configured through ConnectConfig.json in your project root. The SDK creates this file automatically when you integrate it into your app.

This file is required. The SDK ships with built-in defaults for most settings, except your credentials (AppKey and PostMessageUrl) and, if you enable push, the push-specific settings that have no usable default — you must provide these yourself. Override other keys only as needed.

Language: TypeScript and JavaScript

Availability: Pro, Premium, and Ultimate

ConnectConfig.json

The SDK postinstall script reads ConnectConfig.json and distributes its values into the underlying native iOS and Android configuration files at build time. Changes take effect after you re-run pod install (iOS) and trigger a Gradle sync (Android).

Credentials

Key	Default	Description
`AppKey`	—	Your Connect application key. Required.
`PostMessageUrl`	—	Your Connect collector URL. Required.
`KillSwitchUrl`	—	Your kill switch URL. Format: `https://{collector_host}/collector/switch/{app_key}`. Required for production — see Move your React Native integration to production.
`KillSwitchEnabled`	`false`	Set to `true` to activate the kill switch on Android. Required alongside `KillSwitchUrl` — setting the URL alone does not enable the kill switch on Android.

Build mode

Key	Default	Description
`useRelease`	`false`	Set to `false` for development and testing. This uses the `AcousticConnectDebug` iOS library and enables verbose SDK logging on both iOS (Xcode console) and Android (Logcat). Set to `true` before shipping to production.

Native library versions

By default, the SDK resolves the latest compatible version of the underlying iOS and Android native libraries. To pin a specific version, set the corresponding key.

Key	Default	Description
`iOSVersion`	`""`	iOS native library version. Empty string uses the latest version. Format: `2.0.5`.
`AndroidVersion`	`""`	Android native library version. Empty string uses the latest version. Format: `11.0.12`.

How to check the supported range

To find the current range for your installed SDK version, check the constraint directly in the package:

# iOS floor
grep "floor =" node_modules/react-native-acoustic-connect/cli/ios/connect_pods.rb

# Android range
grep -A1 "strictly" node_modules/react-native-acoustic-connect/android/build.gradle

Both constraints can change between SDK releases, so re-check them after upgrading if you pin either version.

⚠️
Warning
If pod install fails with [Connect] requires AcousticConnect >= x.x.x, your pinned iOSVersion is too old. Set it to an empty string and re-run pod install. If Gradle fails to resolve the Android artifact, set AndroidVersion to an empty string and re-sync.

Push notifications

Key	Default	Description
`PushEnabled`	`false`	Whether to enable push notification support. See Enable push notifications in a React Native app (iOS) or Enable push notifications in an Expo app (iOS) for setup and prerequisites.
`iOSPushMode`	`"automatic"`	Push registration mode on iOS. `"automatic"` registers for APNs at app startup — the SDK installs its own notification delegate and handles registration, foreground delivery, and tap actions with no `AppDelegate` changes. `"manual"` is for apps that manage their own `AppDelegate` push callbacks and forward events to the SDK — contact Acoustic support to set this up; it is not self-service.
`iOSAppGroupIdentifier`	`null`	App Group identifier for your Notification Service Extension on iOS. Required when `PushEnabled` is `true`. Format: `group.com.example.myapp`.
`AndroidNotificationIconResName`	`null`	Name of the Android drawable resource to use as the notification icon. Format: `ic_notification` (without file extension or folder path).

Layout and masking configuration

The layoutConfigIos and layoutConfigAndroid keys contain screen-level data capture and PII masking settings. Both follow the same structure and are applied independently to each platform.

For step-by-step masking setup, see Mask PII in session replay (React Native).

AutoLayout

The AutoLayout object maps screen names to their capture settings. The special key GlobalScreenSettings is the fallback applied to every screen that doesn't have its own entry.

"AutoLayout": {
  "GlobalScreenSettings": {
    "CaptureScreenVisits": false,
    "CaptureUserEvents": true,
    "CaptureScreenshotOn": 2,
    "CaptureLayoutOn": 2,
    "CaptureLayoutDelay": 1,
    "ScreenShot": true,
    "ScreenChange": true,
    "DisplayName": "",
    "NumberOfWebViews": 0,
    "Masking": { ... }
  },
  "MyScreenName": {
    ...
  }
}

Per-screen settings:

Key	Default (`GlobalScreenSettings`)	Description
`CaptureScreenVisits`	`false`	Whether to log screen view events for this screen.
`CaptureUserEvents`	`true`	Whether to capture user interactions (taps, gestures) on this screen. Set to `false` to pause capture on a specific screen.
`CaptureScreenshotOn`	`2`	When to take screenshots. `0` = disabled, `1` = on user gesture, `2` = on screen load. Note: setting to `0` does not disable screenshots triggered by other interaction events when `ScreenShot` is `true`.
`CaptureLayoutOn`	`2`	When to capture the screen layout. `0` = disabled, `1` = on user gesture, `2` = on screen load.
`CaptureLayoutDelay`	`1`	Delay in milliseconds before capturing the layout after the trigger condition is met. Increase this value for screens that take longer to render.
`ScreenShot`	`true`	Whether to include screenshots in session replay for this screen.
`ScreenChange`	`true`	Whether to track screen changes, showing how users navigate between screens. Does not affect content capture — use `CaptureUserEvents` and `ScreenShot` to control capture.
`DisplayName`	`""`	Human-readable label for this screen as it appears in Connect. Defaults to the screen name key.
`NumberOfWebViews`	`0`	Number of `WebView` components on this screen. Used to optimize layout capture.

Masking

Each screen's Masking object controls PII redaction for that screen.

Key	Description
`HasMasking`	Whether masking is enabled for this screen.
`HasCustomMask`	Whether the custom masking rules in this object apply. When `false`, only the global defaults are used.
`MaskIdList`	Array of regex patterns. Elements whose internal ID matches a pattern are masked.
`MaskValueList`	Array of regex patterns. Elements whose displayed value matches a pattern are masked (for example, credit card number patterns).
`MaskAccessibilityIdList`	Array of regex patterns. Elements whose accessibility ID matches a pattern are masked.
`MaskAccessibilityLabelList`	Array of regex patterns. Elements whose accessibility label matches a pattern are masked.

The Sensitive object defines the replacement characters used when masking matched content:

Key	Default	Description
`number`	`"9"`	Replacement character for digits.
`smallCaseAlphabet`	`"x"`	Replacement character for lowercase letters.
`capitalCaseAlphabet`	`"X"`	Replacement character for uppercase letters.
`symbol`	`"#"`	Replacement character for symbols.

AppendMapIds

AppendMapIds maps element path patterns to custom IDs, which appear in Connect instead of the auto-generated element path. Each entry is a key-value pair where the key is the element path or tag pattern and the value is an object with a mid (mapped ID) property.

"AppendMapIds": {
  "tag2999999": { "mid": "myCustomButton" },
  "idxPathValue": { "mid": "myListItem" }
}

Native configuration files (advanced)

The SDK bundles the same native configuration files used by the native Android and iOS SDKs. These files are listed here for reference. Do not edit them directly — they are managed by the SDK build scripts and any manual changes will be lost on the next install.

Android

To configure Android-specific settings not listed in the ConnectConfig.json section above, add the corresponding key directly to ConnectConfig.json. The Gradle build script reads ConnectConfig.json and distributes values to the underlying native files at build time. The full list of supported keys mirrors the properties documented in the Connect Android SDK configuration reference.

The native files the build script manages are:

ConnectBasicConfig.properties — primary SDK settings (app key, kill switch, screenshots, gestures, sessions, cookies, geolocation).
ConnectAdvancedConfig.json — Android-specific UI capture settings (click events, gesture capture, WebView handling, layout delays).
EOCoreAdvancedConfig.json — data transport and session settings (cache size, compression, timeouts, background behavior).

iOS

AcousticConnectRNConfig.json is an iOS-internal file populated from ConnectConfig.json by the postinstall script. It is not intended to be edited directly — configure iOS push and build mode settings through ConnectConfig.json instead.