Connect React Native SDK public API reference
This page documents the public API of react-native-acoustic-connect. All methods are available in TypeScript and JavaScript.
Language: TypeScript and JavaScript
Package: react-native-acoustic-connect
Imports
The package has two export paths.
Default export — the AcousticConnectRN singleton. Use this for all method calls.
import AcousticConnectRN from 'react-native-acoustic-connect'Named exports — components, hooks, and utilities.
import { Connect } from 'react-native-acoustic-connect'<Connect> component
<Connect> componentThe root wrapper component. Place it at the top of your component tree, wrapping your NavigationContainer. Required for screen tracking, touch capture, and keyboard event interception.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
children | React.ReactNode | Yes | — | Your app's component tree. |
captureKeyboardEvents | boolean | Yes | — | Enables keyboard event capture. Set to true to include text input interactions in session data. |
navigationRef | React.RefObject | No | — | A ref from useNavigationContainerRef(). Recommended — decouples <Connect> from assumptions about the children structure. If omitted, <Connect> attempts to resolve a ref from the direct child, then falls back to injecting one via cloneElement. If no ref can be resolved, screen tracking is disabled but touch capture continues. |
Example
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>
)
}SDK lifecycle
The default export is a singleton native module. The SDK initializes automatically at module load from ConnectConfig.json. The methods below are only needed when you need to pause and resume data capture — for example, in a consent flow.
enable()
enable()Re-enables the SDK after a prior disable() call.
enable(): booleanReturns true if the call was accepted. Idempotent — calling enable() on an already-running SDK is a no-op.
disable()
disable()Disables the SDK and stops all data capture. The SDK flushes pending data, stops listening for events, and releases push state. Call enable() to resume.
disable(): booleanReturns true if the call was accepted. Idempotent.
Screen tracking
setCurrentScreenName(logicalPageName)
setCurrentScreenName(logicalPageName)Manually reports the current screen name to the SDK. Use this when your app does not use React Navigation, or when you need to override the auto-detected screen name.
setCurrentScreenName(logicalPageName: string): boolean| Parameter | Type | Description |
|---|---|---|
logicalPageName | string | The screen name to record. |
Example
AcousticConnectRN.setCurrentScreenName('ProductScreen')logScreenViewContextLoad(logicalPageName, referrer)
logScreenViewContextLoad(logicalPageName, referrer)Logs a screen view load event with an optional referrer.
logScreenViewContextLoad(logicalPageName: string | null | undefined, referrer: string | null | undefined): booleanlogScreenViewContextUnload(logicalPageName, referrer)
logScreenViewContextUnload(logicalPageName, referrer)Logs a screen view unload event with an optional referrer.
logScreenViewContextUnload(logicalPageName: string | null | undefined, referrer: string | null | undefined): booleanlogScreenLayout(name, delay)
logScreenLayout(name, delay)Logs a screen layout event. Called automatically by <Connect> on Android — most apps do not need to call this directly.
logScreenLayout(name: string, delay: number): booleanEvent logging
Custom events
logCustomEvent(eventName, values, level)
logCustomEvent(eventName, values, level)Logs a named custom event with key-value attributes.
logCustomEvent(
eventName: string,
values: Record<string, string | number | boolean>,
level: number
): boolean| Parameter | Type | Description |
|---|---|---|
eventName | string | Name of the event. |
values | Record<string, string | number | boolean> | Attributes to attach to the event. |
level | number | Logging level. |
Example
AcousticConnectRN.logCustomEvent('AddToCart', {
productId: 'hrn-007',
price: 48.00,
inStock: true,
}, 1)logSignal(values, level)
logSignal(values, level)Logs a generic signal with key-value attributes.
logSignal(values: Record<string, string | number | boolean>, level: number): booleanlogExceptionEvent(message, stackInfo, unhandled)
logExceptionEvent(message, stackInfo, unhandled)Logs an exception. Uncaught JavaScript exceptions are forwarded automatically — most apps do not need to call this directly.
logExceptionEvent(message: string, stackInfo: string, unhandled: boolean): booleanLocation
logLocation()
logLocation()Logs the device's current location. Requires location permission.
On iOS, the SDK logs location only when you call this method. On Android, the SDK can also log location automatically when your app has location permission, because LogLocationEnabled is true by default. To turn that off, add "LogLocationEnabled": false to the Connect object in ConnectConfig.json, then rebuild.
logLocation(): booleanlogLocationWithLatitudeLongitude(latitude, longitude, level)
logLocationWithLatitudeLongitude(latitude, longitude, level)Logs a specific latitude/longitude pair, for example from your own location service.
logLocationWithLatitudeLongitude(
latitude: number,
longitude: number,
level: number
): booleanUser interactions
Note
logClickEventandlogTextChangeEventare called automatically by<Connect>. Most apps do not need to call them directly.
logClickEvent(target, controlId)
logClickEvent(target, controlId)Logs a touch/click event on a control.
logClickEvent(target: number, controlId: string): booleanlogTextChangeEvent(target, controlId, text)
logTextChangeEvent(target, controlId, text)Logs a text change event on an input field.
logTextChangeEvent(target: number, controlId: string, text: string | null | undefined): booleanUser identity
logIdentity(identifierName, identifierValue, signalType?, additionalParameters?)
logIdentity(identifierName, identifierValue, signalType?, additionalParameters?)Associates the current session with a known Connect contact. Returns a Promise — the native bridge hops to the main thread to call the native identity API.
logIdentity(
identifierName: string,
identifierValue: string,
signalType?: string,
additionalParameters?: Record<string, string>
): Promise<boolean>| Parameter | Type | Required | Description |
|---|---|---|---|
identifierName | string | Yes | Identifier type, e.g. 'Email'. |
identifierValue | string | Yes | Identifier value, e.g. '[email protected]'. |
signalType | string | No | Signal type. Required by the backend — the SDK sends 'loggedIn' when omitted. |
additionalParameters | Record<string, string> | No | Extra key-value pairs merged into the signal payload. When omitted, { registrationMethod: 'email' } is added by default. Pass an explicit {} to send no extra parameters. |
Returns a Promise<boolean> that resolves to true if the signal was dispatched. Never rejects. Returns false if either identifier field is blank after trimming.
Example
await AcousticConnectRN.logIdentity('Email', '[email protected]')Push notifications
Permission management
pushRequestPermission()
pushRequestPermission()Requests notification permission, presenting the system prompt when the state is undetermined. Always resolves, never rejects.
On iOS, if push is disabled (PushEnabled is false in ConnectConfig.json), the system prompt isn't shown. The call resolves with granted: false and a non-null error, so check error before treating granted: false as a user denial. On Android, the SDK doesn't check PushEnabled: if your app declares the POST_NOTIFICATIONS permission, the system prompt is shown and the real state is returned; if it doesn't (for example an Expo app built with push off), the call returns granted: false without a prompt.
pushRequestPermission(): Promise<PushPermissionResult>Returns a PushPermissionResult.
pushGetPermissionState()
pushGetPermissionState()Reads the current notification permission state without prompting.
pushGetPermissionState(): Promise<boolean | null>Returns true (granted), false (denied), or null (not yet determined). On iOS, also returns null when the state can't be read, for example when push is disabled in ConnectConfig.json.
pushDidReceiveAuthorization(granted, error?)
pushDidReceiveAuthorization(granted, error?)Forwards externally-obtained permission state to the SDK — for example, when your app manages permissions through its own permission library.
pushDidReceiveAuthorization(granted: boolean | null, error?: PushErrorInfo): Promise<boolean>| Parameter | Type | Description |
|---|---|---|
granted | boolean | null | true granted, false denied, null not yet determined. |
error | PushErrorInfo | Optional error accompanying a denial. |
APNs lifecycle (iOS, manual mode only)
These methods forward APNs lifecycle events to the Connect SDK. They are only needed in manual push mode — in automatic mode the SDK's delegate handles everything.
pushDidRegisterWithToken(deviceToken)
pushDidRegisterWithToken(deviceToken)Forwards the raw APNs device token to the SDK.
pushDidRegisterWithToken(deviceToken: ArrayBuffer): Promise<boolean>pushDidFailToRegister(error)
pushDidFailToRegister(error)Forwards an APNs registration failure to the SDK.
pushDidFailToRegister(error: PushErrorInfo): Promise<boolean>pushDidReceiveNotification(userInfo)
pushDidReceiveNotification(userInfo)Forwards a received notification to the SDK so it can log a pushReceived signal. Returns false in automatic or off mode.
pushDidReceiveNotification(
userInfo: Record<string, string | number | boolean>
): Promise<boolean>pushDidReceiveResponse(actionIdentifier, userInfo)
pushDidReceiveResponse(actionIdentifier, userInfo)Forwards a notification response (tap or action) to the SDK. Returns false in automatic or off mode.
pushDidReceiveResponse(
actionIdentifier: string,
userInfo: Record<string, string | number | boolean>
): Promise<boolean>Configuration
These methods read and write SDK configuration values at runtime. Use with caution — most configuration should live in ConnectConfig.json.
| Method | Signature | Description |
|---|---|---|
setStringItemForKey | (key, value, moduleName): boolean | Sets a string config value. |
setBooleanConfigItemForKey | (key, value, moduleName): boolean | Sets a boolean config value. |
setNumberItemForKey | (key, value, moduleName): boolean | Sets a numeric config value. |
setConfigItemForKey | (key, value, moduleName): boolean | Sets a config value of any supported type. |
getStringItemForKey | (theDefault, key, moduleName): string | null | undefined | Gets a string config value. |
getBooleanConfigItemForKey | (theDefault, key, moduleName): boolean | Gets a boolean config value. |
getNumberItemForKey | (theDefault, key, moduleName): number | Gets a numeric config value. |
Set moduleName to the module the key belongs to:
'Connect'for Connect settings'EOCore'for EOCore settings (such as posting and caching)
On iOS, moduleName isn't used: the SDK looks up the key on its own. Pass it anyway so the same code works on Android.
Type reference
PushErrorInfo
PushErrorInfoStructured error for APNs and permission failures.
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Human-readable failure description. |
code | number | No | Platform error code (NSError.code on iOS). |
domain | string | No | Platform error domain (NSError.domain on iOS). |
PushPermissionResult
PushPermissionResultResult of a pushRequestPermission() call.
| Field | Type | Description |
|---|---|---|
granted | boolean | true if permission was granted. |
error | string | null | null on success or clean denial. A non-null string contains the system error description, an error when push is disabled (iOS), or 'permission-prompt-abandoned' if the host was destroyed mid-prompt. |
Updated 6 days ago
