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

The 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

PropTypeRequiredDefaultDescription
childrenReact.ReactNodeYes—Your app's component tree.
captureKeyboardEventsbooleanYes—Enables keyboard event capture. Set to true to include text input interactions in session data.
navigationRefReact.RefObjectNo—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()

Re-enables the SDK after a prior disable() call.

enable(): boolean

Returns true if the call was accepted. Idempotent — calling enable() on an already-running SDK is a no-op.

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(): boolean

Returns true if the call was accepted. Idempotent.


Screen tracking

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
ParameterTypeDescription
logicalPageNamestringThe screen name to record.

Example

AcousticConnectRN.setCurrentScreenName('ProductScreen')

logScreenViewContextLoad(logicalPageName, referrer)

Logs a screen view load event with an optional referrer.

logScreenViewContextLoad(logicalPageName: string | null | undefined, referrer: string | null | undefined): boolean

logScreenViewContextUnload(logicalPageName, referrer)

Logs a screen view unload event with an optional referrer.

logScreenViewContextUnload(logicalPageName: string | null | undefined, referrer: string | null | undefined): boolean

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): boolean

Event logging

Custom events

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
ParameterTypeDescription
eventNamestringName of the event.
valuesRecord<string, string | number | boolean>Attributes to attach to the event.
levelnumberLogging level.

Example

AcousticConnectRN.logCustomEvent('AddToCart', {
  productId: 'hrn-007',
  price: 48.00,
  inStock: true,
}, 1)

logSignal(values, level)

Logs a generic signal with key-value attributes.

logSignal(values: Record<string, string | number | boolean>, level: number): boolean

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): boolean

Location

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(): boolean

logLocationWithLatitudeLongitude(latitude, longitude, level)

Logs a specific latitude/longitude pair, for example from your own location service.

logLocationWithLatitudeLongitude(
  latitude: number,
  longitude: number,
  level: number
): boolean

User interactions

📘

Note

logClickEvent and logTextChangeEvent are called automatically by <Connect>. Most apps do not need to call them directly.

logClickEvent(target, controlId)

Logs a touch/click event on a control.

logClickEvent(target: number, controlId: string): boolean

logTextChangeEvent(target, controlId, text)

Logs a text change event on an input field.

logTextChangeEvent(target: number, controlId: string, text: string | null | undefined): boolean

User identity

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>
ParameterTypeRequiredDescription
identifierNamestringYesIdentifier type, e.g. 'Email'.
identifierValuestringYesIdentifier value, e.g. '[email protected]'.
signalTypestringNoSignal type. Required by the backend — the SDK sends 'loggedIn' when omitted.
additionalParametersRecord<string, string>NoExtra 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()

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

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

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>
ParameterTypeDescription
grantedboolean | nulltrue granted, false denied, null not yet determined.
errorPushErrorInfoOptional 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)

Forwards the raw APNs device token to the SDK.

pushDidRegisterWithToken(deviceToken: ArrayBuffer): Promise<boolean>

pushDidFailToRegister(error)

Forwards an APNs registration failure to the SDK.

pushDidFailToRegister(error: PushErrorInfo): Promise<boolean>

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)

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.

MethodSignatureDescription
setStringItemForKey(key, value, moduleName): booleanSets a string config value.
setBooleanConfigItemForKey(key, value, moduleName): booleanSets a boolean config value.
setNumberItemForKey(key, value, moduleName): booleanSets a numeric config value.
setConfigItemForKey(key, value, moduleName): booleanSets a config value of any supported type.
getStringItemForKey(theDefault, key, moduleName): string | null | undefinedGets a string config value.
getBooleanConfigItemForKey(theDefault, key, moduleName): booleanGets a boolean config value.
getNumberItemForKey(theDefault, key, moduleName): numberGets 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

Structured error for APNs and permission failures.

FieldTypeRequiredDescription
messagestringYesHuman-readable failure description.
codenumberNoPlatform error code (NSError.code on iOS).
domainstringNoPlatform error domain (NSError.domain on iOS).

PushPermissionResult

Result of a pushRequestPermission() call.

FieldTypeDescription
grantedbooleantrue if permission was granted.
errorstring | nullnull 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.

Did this page help you?