This page documents the public API of react-native-acoustic-connect-beta. All methods are available in TypeScript and JavaScript.

Language: TypeScript and JavaScript

Package: react-native-acoustic-connect-beta

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-beta'

Named exports — components, hooks, and utilities.

import { Connect } from 'react-native-acoustic-connect-beta'

<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

Example

import { useNavigationContainerRef, NavigationContainer } from '@react-navigation/native'
import { Connect } from 'react-native-acoustic-connect-beta'

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

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

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. Location capture is an explicit opt-in — the SDK does not collect location automatically.

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>

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.

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

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>

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.

Type reference

PushErrorInfo

Structured error for APNs and permission failures.

PushPermissionResult

Result of a pushRequestPermission() call.