react-native-acoustic-connect-beta 19.0.13 → 19.0.15

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

@@ -10,7 +10,7 @@
 //  Created on 5/9/25.
 //
 
-import { type HybridObject } from 'react-native-nitro-modules'
+import { type AnyMap, type HybridObject } from 'react-native-nitro-modules'
 
 // Define a named type for the anonymous object
 export type KeyValueObject = {
@@ -18,6 +18,32 @@ export type KeyValueObject = {
     [key: string]: unknown;
 };
 
+/**
+ * Payload accepted by {@link AcousticConnectRN.logSignal} — any JSON-shaped
+ * object. Nested objects and arrays are allowed, so this is a superset of a
+ * flat `Record<string, string | number | boolean>`.
+ *
+ * You do not need this type to call `logSignal`: an object literal is enough.
+ * It exists for the times you want to name the payload — a helper parameter, a
+ * shared constant — and is re-exported from the package root so you never have
+ * to reach into `react-native-nitro-modules` for it:
+ *
+ * ```ts
+ * import AcousticConnectRN, { type SignalValues } from 'react-native-acoustic-connect-beta'
+ *
+ * const payload: SignalValues = { signalContent: { signalType: 'pageview' } }
+ * AcousticConnectRN.logSignal(payload, 1)
+ * ```
+ *
+ * @remarks
+ * Aliases nitro's `AnyMap`, which is the only way to express arbitrary JSON in
+ * a Nitro spec — a hand-rolled recursive type is rejected by nitrogen, which
+ * tries to generate a struct for it. Nitrogen resolves the alias, so the
+ * generated native bindings are identical either way; the indirection exists
+ * purely to keep a third-party type name off our public API.
+ */
+export type SignalValues = AnyMap
+
 export type ConnectMonitoringLevelType = 'Ignore' | 'CellularAndWiFi' | 'WiFi'
 
 /**
@@ -123,8 +149,75 @@ export interface AcousticConnectRN extends HybridObject<{ ios: 'swift', android:
     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
+    /**
+     * Logs a named custom event with a flat set of key/value pairs.
+     *
+     * `values` is deliberately **flat** (scalars only), unlike
+     * {@link logSignal}. The Android SDK's custom-event path is typed
+     * `HashMap<String, String>` end to end (`Connect.logCustomEvent` →
+     * `Tealeaf.logCustomEvent`), so there is no native route for nested
+     * JSON. Widening this signature would compile but silently drop the
+     * nesting on Android while preserving it on iOS — a cross-platform
+     * divergence worse than the restriction. Use {@link logSignal} when the
+     * payload needs structure.
+     *
+     * @param eventName Event name; appears in the posted JSON.
+     * @param values Flat key/value pairs to attach to the event.
+     * @param level Monitoring level for this event.
+     * @returns `true` if the event was queued.
+     */
     logCustomEvent(eventName: string, values: Record<string, string | number | boolean>, level: number): boolean
-    logSignal(values: Record<string, string | number | boolean>, level: number): boolean
+
+    /**
+     * Logs a signal payload.
+     *
+     * `values` accepts **arbitrary JSON** — nested objects and arrays, not
+     * just scalars — because both native SDKs embed the payload verbatim:
+     * iOS `CTSignalMessage` gates only on `NSJSONSerialization
+     * isValidJSONObject:`, and Android `Connect.logSignal` takes an untyped
+     * `HashMap<String, Any?>`. The bridge converts the map to each
+     * platform's JSON representation without flattening or reshaping it.
+     *
+     * Scalar-only callers are unaffected: {@link SignalValues} is a superset
+     * of `Record<string, string | number | boolean>`.
+     *
+     * @param values Signal payload. Objects, arrays, strings, numbers,
+     *   booleans and `null` are all carried through.
+     * @param level Monitoring level for this signal.
+     * @returns `true` if the signal was queued.
+     *
+     * @remarks
+     * **Android limitation — top-level numbers.** The Android SDK's
+     * `JsonUtil.getHashValues` serialises only `String`, `Boolean`,
+     * `JSONObject`, `JSONArray` and `byte[]` at the top level of the signal
+     * map; a top-level numeric value is dropped. Numbers nested *inside* an
+     * object or array are unaffected, because the bridge builds those
+     * `JSONObject`/`JSONArray` values itself. iOS carries top-level numbers
+     * normally. Send numbers inside a nested object when cross-platform
+     * parity matters. This is a pre-existing SDK-side gap, not a
+     * restriction of this bridge.
+     *
+     * @example Nested payload
+     * ```ts
+     * import AcousticConnectRN from 'react-native-acoustic-connect-beta'
+     *
+     * AcousticConnectRN.logSignal(
+     *   {
+     *     signalContent: {
+     *       signalType: 'pageview',
+     *       url: 'https://app.example.com/dashboard',
+     *       pageCategory: 'dashboard',
+     *     },
+     *     audience: [
+     *       { name: 'Account Name', value: 'Acme Corp' },
+     *       { name: 'Account ID', value: '4815162342' },
+     *     ],
+     *   },
+     *   1
+     * )
+     * ```
+     */
+    logSignal(values: SignalValues, level: number): boolean
     logExceptionEvent(message: string, stackInfo: string, unhandled: boolean): boolean
     logLocation(): boolean
     logLocationWithLatitudeLongitude(latitude: number, longitude: number, level: number): boolean
@@ -138,6 +231,13 @@ export interface AcousticConnectRN extends HybridObject<{ ios: 'swift', android:
     logDialogShowEvent(dialogId: string, dialogTitle: string, dialogType: string): boolean
     logDialogDismissEvent(dialogId: string, dismissReason: string): boolean
     logDialogButtonClickEvent(dialogId: string, buttonText: string, buttonIndex: number): boolean
+    /**
+     * Logs a custom event against a tracked dialog.
+     *
+     * `values` is flat for the same reason as {@link logCustomEvent} — this
+     * routes to the native custom-event API, whose Android path carries string
+     * values only.
+     */
     logDialogCustomEvent(dialogId: string, eventName: string, values: Record<string, string | number | boolean>): boolean
 
     /**
@@ -161,23 +261,54 @@ export interface AcousticConnectRN extends HybridObject<{ ios: 'swift', android:
      *   `'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).
+     *   signal payload. Only when omitted (`undefined`) does the bridge supply a
+     *   default, and that default follows the resolved `signalType` — see
+     *   **Required method attribute** below. 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
+     * ### Required method attribute
+     *
+     * Identity signals must carry a *method* attribute, and the key Connect
+     * requires depends on the signal type:
+     *
+     * | `signalType`         | Required attribute   |
+     * | -------------------- | -------------------- |
+     * | `'loggedIn'`         | `loginMethod`        |
+     * | `'accountRegistered'`| `registrationMethod` |
+     *
+     * Send the wrong key and the signal fails schema validation and is
+     * discarded server-side — while this promise still resolves `true`, because
+     * the native SDKs report only that the signal was queued. If you pass
+     * `additionalParameters` explicitly, you own supplying the right key.
+     *
+     * @example Sign-in — `loginMethod` is required
      * ```ts
      * import AcousticConnectRN from 'react-native-acoustic-connect-beta'
      *
+     * await AcousticConnectRN.logIdentity('Email', 'user@example.com', 'loggedIn', {
+     *   loginMethod: 'sso',
+     * })
+     *
+     * // Omitting both arguments is equivalent to the above with
+     * // `{ loginMethod: 'email' }` — the bridge defaults to a `loggedIn` signal.
      * await AcousticConnectRN.logIdentity('Email', 'user@example.com')
      * ```
+     *
+     * @example Registration — `registrationMethod` is required
+     * ```ts
+     * await AcousticConnectRN.logIdentity(
+     *   'Email',
+     *   'user@example.com',
+     *   'accountRegistered',
+     *   { registrationMethod: 'email' }
+     * )
+     * ```
      */
     logIdentity(
         identifierName: string,

package/Examples/SampleUI/ConnectConfig.json

@@ -1,180 +0,0 @@
-{
-    "Connect": {
-        "AndroidVersion": "10.4.48",
-        "AppKey": "fa47722a7fef4bcd8677fd8d6d113a0d",
-        "KillSwitchUrl": "https://lib-us-2.brilliantcollector.com/collector/switch/b6c3709b7a4c479bb4b5a9fb8fec324c",
-        "PostMessageUrl": "https://lib-us-2.brilliantcollector.com/collector/collectorPost",
-        "iOSVersion": "",
-        "layoutConfigAndroid": {
-            "AppendMapIds": {
-                "[w,9290],[v,0]": {
-                    "mid": "ASimpleUIView"
-                },
-                "idxPathValue": {
-                    "mid": "giveAdditionalId2"
-                },
-                "tag2999999": {
-                    "mid": "giveAdditionalId1"
-                }
-            },
-            "AutoLayout": {
-                "ExampleMaskingPage": {
-                    "CaptureLayoutDelay": 0,
-                    "CaptureLayoutOn": 0,
-                    "CaptureScreenVisits": false,
-                    "CaptureScreenshotOn": 0,
-                    "CaptureUserEvents": false,
-                    "DisplayName": "",
-                    "Masking": {
-                        "HasCustomMask": true,
-                        "HasMasking": true,
-                        "MaskAccessibilityIdList": [
-                            
-                        ],
-                        "MaskAccessibilityLabelList": [
-                            
-                        ],
-                        "MaskIdList": [
-                            "^9[0-9][0-9][0-9]$",
-                            "^\\[wvv,0\\],\\[dddv,0\\],\\[v,0\\],\\[v,0\\],\\[v,0\\],\\[b,0\\](.)*$"
-                        ],
-                        "MaskValueList": [
-                            "^4[0-9]{12}(?:[0-9]{3})?$",
-                            "^3[47][0-9]{13}$",
-                            "^65[4-9][0-9]{13}|64[4-9][0-9]{13}|6011[0-9]{12}|(622(?:12[6-9]|1[3-9][0-9]|[2-8][0-9][0-9]|9[01][0-9]|92[0-5])[0-9]{10})$",
-                            "^(5[1-5][0-9]{14}|2(22[1-9][0-9]{12}|2[3-9][0-9]{13}|[3-6][0-9]{14}|7[0-1][0-9]{13}|720[0-9]{12}))$"
-                        ],
-                        "Sensitive": {
-                            "capitalCaseAlphabet": "X",
-                            "number": "9",
-                            "smallCaseAlphabet": "x",
-                            "symbol": "#"
-                        }
-                    },
-                    "NumberOfWebViews": 0,
-                    "ScreenChange": false,
-                    "ScreenShot": false
-                },
-                "GlobalScreenSettings": {
-                    "CaptureLayoutDelay": 1,
-                    "CaptureLayoutOn": 2,
-                    "CaptureScreenVisits": false,
-                    "CaptureScreenshotOn": 2,
-                    "CaptureUserEvents": true,
-                    "DisplayName": "",
-                    "Masking": {
-                        "HasCustomMask": true,
-                        "HasMasking": true,
-                        "MaskAccessibilityIdList": [
-                            
-                        ],
-                        "MaskAccessibilityLabelList": [
-                            
-                        ],
-                        "MaskIdList": [
-                            
-                        ],
-                        "MaskValueList": [
-                            
-                        ],
-                        "Sensitive": {
-                            "capitalCaseAlphabet": "X",
-                            "number": "9",
-                            "smallCaseAlphabet": "x",
-                            "symbol": "#"
-                        }
-                    },
-                    "NumberOfWebViews": 0,
-                    "ScreenChange": true,
-                    "ScreenShot": true
-                }
-            }
-        },
-        "layoutConfigIos": {
-            "AppendMapIds": {
-                "[w,9290],[v,0]": {
-                    "mid": "ASimpleUIView"
-                },
-                "idxPathValue": {
-                    "mid": "giveAdditionalId2"
-                },
-                "tag2999999": {
-                    "mid": "giveAdditionalId1"
-                }
-            },
-            "AutoLayout": {
-                "ExampleMaskingPage": {
-                    "CaptureLayoutDelay": 0,
-                    "CaptureLayoutOn": 0,
-                    "CaptureScreenVisits": false,
-                    "CaptureScreenshotOn": 0,
-                    "CaptureUserEvents": false,
-                    "DisplayName": "",
-                    "Masking": {
-                        "HasCustomMask": true,
-                        "HasMasking": true,
-                        "MaskAccessibilityIdList": [
-                            
-                        ],
-                        "MaskAccessibilityLabelList": [
-                            
-                        ],
-                        "MaskIdList": [
-                            "^9[0-9][0-9][0-9]$",
-                            "^\\[wvv,0\\],\\[dddv,0\\],\\[v,0\\],\\[v,0\\],\\[v,0\\],\\[b,0\\](.)*$"
-                        ],
-                        "MaskValueList": [
-                            "^4[0-9]{12}(?:[0-9]{3})?$",
-                            "^3[47][0-9]{13}$",
-                            "^65[4-9][0-9]{13}|64[4-9][0-9]{13}|6011[0-9]{12}|(622(?:12[6-9]|1[3-9][0-9]|[2-8][0-9][0-9]|9[01][0-9]|92[0-5])[0-9]{10})$",
-                            "^(5[1-5][0-9]{14}|2(22[1-9][0-9]{12}|2[3-9][0-9]{13}|[3-6][0-9]{14}|7[0-1][0-9]{13}|720[0-9]{12}))$"
-                        ],
-                        "Sensitive": {
-                            "capitalCaseAlphabet": "X",
-                            "number": "9",
-                            "smallCaseAlphabet": "x",
-                            "symbol": "#"
-                        }
-                    },
-                    "NumberOfWebViews": 0,
-                    "ScreenChange": false,
-                    "ScreenShot": false
-                },
-                "GlobalScreenSettings": {
-                    "CaptureLayoutDelay": 1,
-                    "CaptureLayoutOn": 2,
-                    "CaptureScreenVisits": false,
-                    "CaptureScreenshotOn": 2,
-                    "CaptureUserEvents": true,
-                    "DisplayName": "",
-                    "Masking": {
-                        "HasCustomMask": true,
-                        "HasMasking": true,
-                        "MaskAccessibilityIdList": [
-                            
-                        ],
-                        "MaskAccessibilityLabelList": [
-                            
-                        ],
-                        "MaskIdList": [
-                            
-                        ],
-                        "MaskValueList": [
-                            
-                        ],
-                        "Sensitive": {
-                            "capitalCaseAlphabet": "X",
-                            "number": "9",
-                            "smallCaseAlphabet": "x",
-                            "symbol": "#"
-                        }
-                    },
-                    "NumberOfWebViews": 0,
-                    "ScreenChange": true,
-                    "ScreenShot": true
-                }
-            }
-        },
-        "useRelease": false
-    }
-}