react-native-acoustic-connect 16.0.39 → 19.0.3

package/src/examples/HOCDialogExample.tsx

@@ -0,0 +1,253 @@
+/********************************************************************************************
+* Copyright (C) 2025 Acoustic, L.P. All rights reserved.
+*
+* NOTICE: This file contains material that is confidential and proprietary to
+* Acoustic, L.P. and/or other developers. No license is granted under any intellectual or
+* industrial property rights of Acoustic, L.P. except as may be provided in an agreement with
+* Acoustic, L.P. Any unauthorized copying or distribution of content from this file is
+* prohibited.
+********************************************************************************************/
+
+import * as React from 'react';
+import { View, Text, TouchableOpacity, StyleSheet, Alert } from 'react-native';
+import Connect from '../components/Connect';
+
+/**
+ * Example demonstrating HOC-based Paper Dialog tracking
+ * 
+ * This approach requires minimal code changes:
+ * 1. Create tracked versions of your dialog components
+ * 2. Use the tracked versions instead of the original ones
+ * 3. All dialog events are automatically tracked!
+ */
+const HOCDialogExample: React.FC = () => {
+  const [dialogVisible, setDialogVisible] = React.useState(false);
+
+  // Example 1: React Native Alert.alert (automatically tracked)
+  const showAlertDialog = () => {
+    Alert.alert(
+      'Confirmation Alert',
+      'This is a native alert dialog that is automatically tracked.',
+      [
+        { text: 'Cancel', style: 'cancel' },
+        { text: 'OK', onPress: () => console.log('Alert OK pressed') }
+      ]
+    );
+  };
+
+  // Example 2: Paper Dialog with HOC tracking
+  const showPaperDialog = () => {
+    setDialogVisible(true);
+  };
+
+  const hidePaperDialog = () => {
+    setDialogVisible(false);
+  };
+
+  return (
+    <Connect captureDialogEvents={true} captureKeyboardEvents={false}>
+      <View style={styles.container}>
+        <Text style={styles.title}>HOC Dialog Tracking Example</Text>
+        <Text style={styles.subtitle}>
+          Minimal code changes required - just wrap your dialog components!
+        </Text>
+
+        <View style={styles.buttonContainer}>
+          <TouchableOpacity style={styles.button} onPress={showAlertDialog}>
+            <Text style={styles.buttonText}>Show Alert.alert</Text>
+            <Text style={styles.buttonSubtext}>Automatically tracked</Text>
+          </TouchableOpacity>
+
+          <TouchableOpacity style={styles.button} onPress={showPaperDialog}>
+            <Text style={styles.buttonText}>Show Paper Dialog (HOC)</Text>
+            <Text style={styles.buttonSubtext}>Minimal code changes</Text>
+          </TouchableOpacity>
+        </View>
+
+        <View style={styles.infoContainer}>
+          <Text style={styles.infoTitle}>How to use HOC approach:</Text>
+          <Text style={styles.infoText}>1. Create tracked dialog components</Text>
+          <Text style={styles.infoText}>2. Use tracked versions instead of originals</Text>
+          <Text style={styles.infoText}>3. All events automatically tracked!</Text>
+          <Text style={styles.infoText}>4. No manual tracking code needed</Text>
+        </View>
+
+        <View style={styles.codeContainer}>
+          <Text style={styles.codeTitle}>Example Setup Code:</Text>
+          <Text style={styles.codeText}>
+            {`// In your app setup
+import { withAcousticAutoDialog } from 'react-native-acoustic-connect';
+import { Dialog, Portal } from 'react-native-paper';
+
+// Create tracked versions
+const TrackedDialog = withAcousticAutoDialog(Dialog);
+const TrackedPortal = withAcousticAutoDialog(Portal);
+
+// Use TrackedDialog instead of Dialog - that's it!`}
+          </Text>
+        </View>
+
+        {/* Example of how the tracked dialog would be used */}
+        {dialogVisible && (
+          <View style={styles.exampleDialog}>
+            <Text style={styles.dialogTitle}>Example Dialog</Text>
+            <Text style={styles.dialogContent}>
+              This shows how you would use the tracked dialog components.
+              In a real app, you would use TrackedDialog instead of Dialog.
+            </Text>
+            <View style={styles.dialogActions}>
+              <TouchableOpacity style={styles.dialogButton} onPress={hidePaperDialog}>
+                <Text style={styles.dialogButtonText}>Cancel</Text>
+              </TouchableOpacity>
+              <TouchableOpacity 
+                style={[styles.dialogButton, styles.primaryButton]} 
+                onPress={() => {
+                  console.log('Dialog confirmed!');
+                  hidePaperDialog();
+                }}
+              >
+                <Text style={styles.dialogButtonText}>Confirm</Text>
+              </TouchableOpacity>
+            </View>
+          </View>
+        )}
+      </View>
+    </Connect>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    backgroundColor: '#f5f5f5',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    textAlign: 'center',
+    marginBottom: 10,
+    color: '#333',
+  },
+  subtitle: {
+    fontSize: 16,
+    textAlign: 'center',
+    marginBottom: 30,
+    color: '#666',
+    fontStyle: 'italic',
+  },
+  buttonContainer: {
+    gap: 15,
+  },
+  button: {
+    backgroundColor: '#007AFF',
+    padding: 15,
+    borderRadius: 10,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 3,
+  },
+  buttonText: {
+    color: 'white',
+    fontSize: 16,
+    fontWeight: '600',
+    textAlign: 'center',
+  },
+  buttonSubtext: {
+    color: 'rgba(255, 255, 255, 0.8)',
+    fontSize: 12,
+    textAlign: 'center',
+    marginTop: 2,
+  },
+  infoContainer: {
+    backgroundColor: 'white',
+    padding: 20,
+    borderRadius: 10,
+    marginTop: 30,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.1,
+    shadowRadius: 2,
+    elevation: 2,
+  },
+  infoTitle: {
+    fontSize: 18,
+    fontWeight: '600',
+    marginBottom: 10,
+    color: '#333',
+  },
+  infoText: {
+    fontSize: 14,
+    color: '#666',
+    marginBottom: 5,
+  },
+  codeContainer: {
+    backgroundColor: '#f8f9fa',
+    padding: 15,
+    borderRadius: 8,
+    marginTop: 20,
+    borderLeftWidth: 4,
+    borderLeftColor: '#007AFF',
+  },
+  codeTitle: {
+    fontSize: 16,
+    fontWeight: '600',
+    marginBottom: 10,
+    color: '#333',
+  },
+  codeText: {
+    fontSize: 12,
+    color: '#555',
+    fontFamily: 'monospace',
+    lineHeight: 18,
+  },
+  exampleDialog: {
+    position: 'absolute',
+    top: '50%',
+    left: 20,
+    right: 20,
+    backgroundColor: 'white',
+    borderRadius: 12,
+    padding: 20,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.25,
+    shadowRadius: 8,
+    elevation: 8,
+  },
+  dialogTitle: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    marginBottom: 15,
+    color: '#333',
+  },
+  dialogContent: {
+    fontSize: 16,
+    color: '#666',
+    marginBottom: 20,
+    lineHeight: 22,
+  },
+  dialogActions: {
+    flexDirection: 'row',
+    justifyContent: 'flex-end',
+    gap: 10,
+  },
+  dialogButton: {
+    paddingHorizontal: 20,
+    paddingVertical: 10,
+    borderRadius: 6,
+    backgroundColor: '#f0f0f0',
+  },
+  primaryButton: {
+    backgroundColor: '#007AFF',
+  },
+  dialogButtonText: {
+    fontSize: 16,
+    fontWeight: '600',
+    color: '#333',
+  },
+});
+
+export default HOCDialogExample; 

package/src/index.ts

@@ -0,0 +1,44 @@
+/********************************************************************************************
+* Copyright (C) 2025 Acoustic, L.P. All rights reserved.
+*
+* NOTICE: This file contains material that is confidential and proprietary to
+* Acoustic, L.P. and/or other developers. No license is granted under any intellectual or
+* industrial property rights of Acoustic, L.P. except as may be provided in an agreement with
+* Acoustic, L.P. Any unauthorized copying or distribution of content from this file is
+* prohibited.
+* 
+* Created on 5/9/25.
+* 
+********************************************************************************************/
+
+import { NitroModules } from 'react-native-nitro-modules'
+import type { AcousticConnectRN as AcousticConnectRNSpec } from './specs/react-native-acoustic-connect.nitro'
+import Connect from './components/Connect'
+import KeyboardListener from './utils/KeyboardListener'
+import DialogListener from './utils/DialogListener'
+import useDialogTracking from './utils/useDialogTracking'
+import { withAcousticAutoDialog } from './utils/withAcousticAutoDialog'
+import DialogDebugger from './utils/DialogDebugger'
+import TLTRN from './TLTRN'
+
+// Instantiating the native HybridObject is the first thing that fails when the
+// app's `react-native-nitro-modules` runtime does not match the version this SDK
+// was generated against (the generated registration is tightly coupled to the
+// Nitro version — see peerDependencies). Without this guard the failure surfaces
+// as an opaque `ClassNotFoundException` and an `undefined` module far from the
+// cause. Re-throw with an actionable message instead.
+let AcousticConnectRN: AcousticConnectRNSpec
+try {
+  AcousticConnectRN = NitroModules.createHybridObject<AcousticConnectRNSpec>('AcousticConnectRN')
+} catch (error) {
+  throw new Error(
+    '[AcousticConnectRN] Failed to load the native HybridObject. This almost ' +
+      'always means a `react-native-nitro-modules` version mismatch: this SDK is ' +
+      'built against the exact version declared in its peerDependencies, so your ' +
+      'app must resolve that same version (check `npm ls react-native-nitro-modules`). ' +
+      `Original error: ${String(error)}`
+  )
+}
+
+export { Connect, TLTRN, KeyboardListener, DialogListener, useDialogTracking, DialogDebugger, withAcousticAutoDialog }
+export default AcousticConnectRN

package/src/specs/react-native-acoustic-connect.nitro.ts

@@ -0,0 +1,284 @@
+// Copyright (C) 2025 Acoustic, L.P. All rights reserved.
+//
+// NOTICE: This file contains material that is confidential and proprietary to
+// Acoustic, L.P. and/or other developers. No license is granted under any intellectual or
+// industrial property rights of Acoustic, L.P. except as may be provided in an agreement with
+// Acoustic, L.P. Any unauthorized copying or distribution of content from this file is
+// prohibited.
+//
+//
+//  Created on 5/9/25.
+//
+
+import { type HybridObject } from 'react-native-nitro-modules'
+
+// Define a named type for the anonymous object
+export type KeyValueObject = {
+    placeholder: string; // Add a placeholder property to avoid the "empty struct" error
+    [key: string]: unknown;
+};
+
+export type ConnectMonitoringLevelType = 'Ignore' | 'CellularAndWiFi' | 'WiFi'
+
+/**
+ * Structured error describing an APNs / permission failure.
+ *
+ * Mirrors the `firebase-messaging` / `notifee` ecosystem convention so callers
+ * can forward a native error object without string-encoding it. The native
+ * bridge reconstructs an `NSError` (iOS) from these fields.
+ */
+export interface PushErrorInfo {
+    /** Platform error code, when available (maps to `NSError.code`). */
+    code?: number
+    /** Platform error domain, when available (maps to `NSError.domain`). */
+    domain?: string
+    /** Human-readable failure description (maps to `NSLocalizedDescriptionKey`). */
+    message: string
+}
+
+/**
+ * Result of a permission request.
+ *
+ * The Promise from {@link AcousticConnectRN.pushRequestPermission} always
+ * resolves with this shape and never rejects. `error` is `null` on success or
+ * a denial with no system error; a non-null string carries the system error's
+ * localized description, or `'permission-prompt-abandoned'` if the host was
+ * destroyed mid-prompt.
+ */
+export interface PushPermissionResult {
+    /** `true` if the user granted permission, `false` otherwise. */
+    granted: boolean
+    /** `null` on success/clean denial; otherwise a description of the error. */
+    error?: string | null
+}
+
+export interface AcousticConnectRN extends HybridObject<{ ios: 'swift', android: 'kotlin' }> {
+    /**
+     * Re-enables the Connect SDK after a prior {@link disable} call.
+     *
+     * The SDK auto-initialises at module load time using the values from
+     * `ConnectConfig.json` at the consumer's project root — so for most apps
+     * there is no need to call `enable()` at all. The method exists as the
+     * pair of {@link disable}: if a consent flow, A/B-test gate, or opt-out
+     * toggle previously called `disable()`, calling `enable()` brings the
+     * SDK back up using the same bundled configuration.
+     *
+     * @returns `true` when the call was accepted and dispatched to the native
+     *   SDK. `false` only when the platform cannot satisfy a precondition
+     *   (e.g. Android without an `Application` context yet).
+     *
+     * @remarks
+     * **Single source of truth.** All configuration (AppKey, PostMessageUrl,
+     * push, platform extras) lives in `ConnectConfig.json` at the consumer's
+     * project root. The podspec (iOS) and `config.gradle` (Android) bake
+     * those values into the bundled config that the native bridge reads at
+     * init time. There is no runtime override path — by design, to eliminate
+     * the inconsistency surface that runtime arguments would create against
+     * the bundled config.
+     *
+     * **Idempotency.** Owned by the native SDK. iOS
+     * `ConnectSDK.shared.enable(with:)` short-circuits via
+     * `guard !isEnabled else { return }` in its internal `enableCore`; the
+     * Android `Connect.init` / `Connect.enable` pair behaves the same way
+     * once the SDK is running.
+     *
+     * **Threading.** Returns synchronously; the native SDK call is
+     * fire-and-forget on the main thread / actor.
+     *
+     * @example User opt-in after a prior opt-out
+     * ```ts
+     * import AcousticConnectRN from 'react-native-acoustic-connect'
+     *
+     * function onUserOptIn() {
+     *   AcousticConnectRN.enable()
+     * }
+     * ```
+     */
+    enable(): boolean
+
+    /**
+     * Disables the Connect SDK and stops all data capture.
+     *
+     * After this call the SDK flushes pending data to the backend, stops
+     * listening for events, and releases push state. Call {@link enable}
+     * to bring the SDK back up using the same bundled configuration.
+     *
+     * @returns `true` when the call was accepted and dispatched. Idempotent —
+     *   calling `disable()` on an already-disabled SDK is safe.
+     *
+     * @example User opt-out flow
+     * ```ts
+     * import AcousticConnectRN from 'react-native-acoustic-connect'
+     *
+     * function onUserOptOut() {
+     *   AcousticConnectRN.disable()
+     * }
+     * ```
+     */
+    disable(): boolean
+    setBooleanConfigItemForKey(key: string, value: boolean, moduleName: string): boolean
+    setStringItemForKey(key: string, value: string, moduleName: string): boolean
+    setNumberItemForKey(key: string, value: number, moduleName: string): boolean
+    setConfigItemForKey(key: string, value: string | number | boolean, moduleName: string): boolean
+    getBooleanConfigItemForKey(theDefault: boolean, key: string, moduleName: string): boolean
+    getStringItemForKey(theDefault: string, key: string, moduleName: string):  string | null | undefined
+    getNumberItemForKey(theDefault: number, key: string, moduleName: string): number
+    logCustomEvent(eventName: string, values: Record<string, string | number | boolean>, level: number): boolean
+    logSignal(values: Record<string, string | number | boolean>, level: number): boolean
+    logExceptionEvent(message: string, stackInfo: string, unhandled: boolean): boolean
+    logLocation(): boolean
+    logLocationWithLatitudeLongitude(latitude: number, longitude: number, level: number): boolean
+    logClickEvent(target: number, controlId: string): boolean
+    logTextChangeEvent(target: number, controlId: string, text: string | null | undefined): boolean
+    setCurrentScreenName(logicalPageName: string): boolean
+    logScreenViewContextLoad(logicalPageName: string | null | undefined, referrer:string | null | undefined): boolean
+    logScreenViewContextUnload(logicalPageName: string | null | undefined, referrer:string | null | undefined): boolean
+    logScreenLayout(name: string, delay: number): boolean
+    // New dialog event handling methods
+    logDialogShowEvent(dialogId: string, dialogTitle: string, dialogType: string): boolean
+    logDialogDismissEvent(dialogId: string, dismissReason: string): boolean
+    logDialogButtonClickEvent(dialogId: string, buttonText: string, buttonIndex: number): boolean
+    logDialogCustomEvent(dialogId: string, eventName: string, values: Record<string, string | number | boolean>): boolean
+
+    /**
+     * Logs a user identity so the current device/session can be associated with
+     * a known Connect contact — the foundation for audience building and
+     * cross-channel engagement. Wraps the native identity loggers
+     * (`ConnectSDK.shared.identity.log` on iOS, `Connect.logIdentificationEvent`
+     * on Android).
+     *
+     * Unlike the synchronous analytics loggers above, this returns a `Promise`:
+     * `ConnectSDK.shared` (iOS) is `@MainActor`-isolated, so the bridge hops to the
+     * main actor and resolves with the *real* success/failure value rather than
+     * firing and forgetting.
+     *
+     * The native APIs return `false` — and emit no signal — when either
+     * `identifierName` or `identifierValue` is empty/blank after trimming.
+     *
+     * @param identifierName  Identifier name, e.g. `'Email'`.
+     * @param identifierValue Identifier value, e.g. `'user@example.com'`.
+     * @param signalType      Optional signal type; the bridge supplies
+     *   `'loggedIn'` when omitted (identity logging typically marks a sign-in),
+     *   overriding the native SDKs' own `'pageView'` default.
+     * @param additionalParameters Optional extra key/value pairs merged into the
+     *   signal payload. Only when omitted (`undefined`) does the bridge supply
+     *   the default `{ registrationMethod: 'email' }`; an explicitly-provided
+     *   map is used as-is, so passing an empty `{}` sends no extra parameters
+     *   (the default is not merged in). A `'url'` entry is honoured uniformly on
+     *   both platforms: on Android it is routed to the SDK's explicit `url`
+     *   parameter, on iOS it rides inside the parameter map (where the native
+     *   API expects it).
+     * @returns A promise resolving to `true` if the identity signal was
+     *   dispatched, `false` otherwise (including the blank-identifier case).
+     *   Never rejects.
+     *
+     * @example
+     * ```ts
+     * import AcousticConnectRN from 'react-native-acoustic-connect'
+     *
+     * await AcousticConnectRN.logIdentity('Email', 'user@example.com')
+     * ```
+     */
+    logIdentity(
+        identifierName: string,
+        identifierValue: string,
+        signalType?: string,
+        additionalParameters?: Record<string, string>
+    ): Promise<boolean>
+
+    // ── Push: APNs lifecycle (iOS) ──────────────────────────────────────────
+    //
+    // Push mode (automatic / manual / off) is configured in `ConnectConfig.json`
+    // and enforced by the native SDK — there is no JS-side mode argument. In
+    // automatic mode the SDK's swizzled delegate handles everything and these
+    // forwarding calls are redundant-but-safe; in manual mode they are the only
+    // path for events to reach the SDK.
+
+    /**
+     * Forwards the raw APNs device token to the Connect SDK (manual mode).
+     *
+     * Nitro maps `ArrayBuffer` ↔ `Data` natively; the bridge forwards the bytes
+     * unchanged with no hex conversion and no validation.
+     *
+     * @param deviceToken Raw APNs device-token bytes from
+     *   `didRegisterForRemoteNotificationsWithDeviceToken`.
+     * @returns A promise resolving to `true` once the SDK accepted the token,
+     *   or `false` if the SDK rejected the call (e.g. push not enabled). Never
+     *   rejects.
+     */
+    pushDidRegisterWithToken(deviceToken: ArrayBuffer): Promise<boolean>
+
+    /**
+     * Forwards an APNs registration failure to the Connect SDK (manual mode).
+     *
+     * @param error Structured error; the bridge builds an `NSError` from it.
+     * @returns A promise resolving to `true` once forwarded, `false` on failure.
+     *   Never rejects.
+     */
+    pushDidFailToRegister(error: PushErrorInfo): Promise<boolean>
+
+    /**
+     * Forwards a received notification to the Connect SDK so it can log a
+     * `pushReceived` signal (manual mode).
+     *
+     * The bridge branches on the push mode resolved from `ConnectConfig.json`:
+     * manual mode forwards to the SDK and returns `true`; automatic/off mode
+     * returns `false` (bridge error `EAC-RN-007`) without forwarding, because
+     * the SDK's own delegate already handles delivery in automatic mode and
+     * forwarding would double-log.
+     *
+     * @param userInfo The notification `userInfo` payload.
+     * @returns A promise resolving to `true` if processed (manual mode), or
+     *   `false` in automatic/off mode (`EAC-RN-007`). Never rejects.
+     */
+    pushDidReceiveNotification(userInfo: Record<string, string | number | boolean>): Promise<boolean>
+
+    /**
+     * Forwards a notification response (tap / action) to the Connect SDK so it
+     * can run the built-in action and log a `pushAction` signal (manual mode).
+     *
+     * Same `EAC-RN-007` (`false`) behaviour in automatic mode as
+     * {@link pushDidReceiveNotification}.
+     *
+     * @param actionIdentifier The response action identifier.
+     * @param userInfo The notification `userInfo` payload.
+     * @returns A promise resolving to `true` if processed (manual mode), or
+     *   `false` in automatic/off mode (`EAC-RN-007`). Never rejects.
+     */
+    pushDidReceiveResponse(actionIdentifier: string, userInfo: Record<string, string | number | boolean>): Promise<boolean>
+
+    // ── Push: permission management (cross-platform) ────────────────────────
+
+    /**
+     * Forwards externally-obtained permission state to the SDK.
+     *
+     * Tri-state `granted`: `true` granted, `false` denied, `null` not yet
+     * determined. For `null` the bridge records the state but does not call the
+     * SDK (it has no notion of forwarding "unknown").
+     *
+     * @param granted Tri-state permission value.
+     * @param error Optional structured error accompanying a denial.
+     * @returns A promise resolving to `true` once handled — including the
+     *   `null`/not-determined case, which is intentionally accepted without
+     *   forwarding to the SDK. `false` only if the SDK rejected a forwarded
+     *   state. Never rejects.
+     */
+    pushDidReceiveAuthorization(granted: boolean | null, error?: PushErrorInfo): Promise<boolean>
+
+    /**
+     * Requests notification permission via the SDK, presenting the system prompt
+     * when undetermined.
+     *
+     * Always resolves, never rejects — see {@link PushPermissionResult}.
+     *
+     * @returns The permission result.
+     */
+    pushRequestPermission(): Promise<PushPermissionResult>
+
+    /**
+     * Reads the current notification permission state without prompting.
+     *
+     * @returns Tri-state: `true` granted, `false` denied, `null` not determined.
+     */
+    pushGetPermissionState(): Promise<boolean | null>
+}