react-native-acoustic-connect 19.0.11 → 19.0.34

package/src/TLTRN.ts

@@ -54,7 +54,7 @@ class TLTRN {
   static displayDebug = false;
 
   static myTimer = {
-    handle: null as NodeJS.Timeout | null,
+    handle: null as ReturnType<typeof setInterval> | null,
     started: 0,
     time: 1000,
     /**
@@ -110,11 +110,44 @@ class TLTRN {
     return result;
   };
 
-  static logScreenLayout = (name: string | undefined) => {
+  /**
+   * Sentinel for the native `delay` argument meaning "use the
+   * `CaptureLayoutDelay` configured for this screen". Both bridges resolve it
+   * from the layout config; anything >= 0 is an explicit delay in
+   * milliseconds.
+   */
+  static USE_CONFIGURED_CAPTURE_DELAY = -1;
+
+  /**
+   * Captures the layout of the current screen.
+   *
+   * @param name    Screen name to associate with the capture.
+   * @param delayMs Milliseconds to wait before capturing. Omit it to use the
+   *   `CaptureLayoutDelay` from `ConnectConfig.json` — that is the setting to
+   *   reach for when a screen transition animation is still running and the
+   *   capture would otherwise catch a half-rendered screen. Pass `0` to
+   *   capture immediately.
+   *
+   * Passing no delay used to send a hardcoded `0`, which made
+   * `CaptureLayoutDelay` inert for React Native apps and fired the capture at
+   * the *start* of the transition rather than after it.
+   *
+   * @returns With no `delayMs` — the normal case — only that the capture was
+   *   **scheduled**, not that it produced a layout message. The native
+   *   deferred overload dispatches and returns immediately, so anything that
+   *   goes wrong once it runs (no view controller resolved, layout capture
+   *   gated off by config) cannot be reflected here; those surface in logcat
+   *   / os_log instead. Pass `0` and the value describes the capture itself,
+   *   at the cost of capturing mid-transition.
+   */
+  static logScreenLayout = (name: string | undefined, delayMs?: number) => {
     TLTRN.currentScreen = name || '';
     let result = false
     try {
-      result = AcousticConnectRN.logScreenLayout(TLTRN.currentScreen, 0);
+      result = AcousticConnectRN.logScreenLayout(
+        TLTRN.currentScreen,
+        delayMs === undefined ? TLTRN.USE_CONFIGURED_CAPTURE_DELAY : delayMs
+      );
     } catch (error: Error | any) {
       console.log('LogScreenLayout error: ', error.message);
     }
@@ -168,8 +201,86 @@ class TLTRN {
     return result;
   };
   
+  /**
+   * Keys already warned about, so a call site inside a render or a list loop
+   * warns once rather than on every pass.
+   */
+  static warnedNestedValueSites = new Set<string>();
+
+  /**
+   * Cap on {@link warnedNestedValueSites}.
+   *
+   * The site key includes the nested keys' names, so a payload built from an
+   * API response — per-record ids, timestamps — makes every call a distinct
+   * site, and the set would then grow for the life of the session. By the
+   * hundredth distinct shape the warning has made its point, so it stops
+   * instead of accumulating: bounded memory matters more than warning about
+   * shape 101.
+   */
+  static WARNED_NESTED_VALUE_SITES_MAX = 100;
+
+  /**
+   * Warns when a flat-values payload carries a nested object or array.
+   *
+   * `logCustomEvent`/`logDialogCustomEvent` are typed for flat scalars, but
+   * TypeScript types are erased at runtime: a payload built from an API
+   * response, widened through `any`, or passed from untyped JS reaches the
+   * bridge with its nesting intact. Both platforms then reshape it silently —
+   * Android's SDK chain is typed `HashMap<String, String>` end to end, so a
+   * nested value is stringified into whatever its `toString()` yields — and
+   * the call still returns `true`. `logSignal` is the API that carries nested
+   * JSON on both platforms.
+   *
+   * Warning only: the payload is passed through untouched, so this changes no
+   * behaviour and cannot break a caller who is relying on today's reshaping.
+   *
+   * @param api    Name of the calling API, for the message.
+   * @param values The payload about to cross the bridge.
+   */
+  static warnOnNestedValues = (api: string, values: Record<string, unknown>) => {
+    if (values == null || typeof values !== 'object') {
+      return;
+    }
+    const nested = Object.keys(values).filter((key) => {
+      const value = (values as Record<string, unknown>)[key];
+      return typeof value === 'object' && value !== null;
+    });
+    if (nested.length === 0) {
+      return;
+    }
+    const site = `${api}:${nested.sort().join(',')}`;
+    if (TLTRN.warnedNestedValueSites.has(site)) {
+      return;
+    }
+    if (TLTRN.warnedNestedValueSites.size >= TLTRN.WARNED_NESTED_VALUE_SITES_MAX) {
+      return;
+    }
+    TLTRN.warnedNestedValueSites.add(site);
+    console.warn(
+      `TLTRN.${api}: nested value(s) [${nested.sort().join(', ')}] will be flattened — ` +
+        `${api} carries flat scalars only, and the native SDKs reshape anything else ` +
+        `without reporting it. Use logSignal for nested JSON; it is carried intact on ` +
+        `both platforms.`
+    );
+  };
+
+  /**
+   * Logs a custom event.
+   *
+   * @param eventName Event name, as it appears in the posted JSON.
+   * @param values    Flat key/value pairs. Nested objects and arrays are NOT
+   *   supported here and are reshaped by the native SDKs — use `logSignal`
+   *   for nested JSON.
+   * @param level     Monitoring level for this event.
+   * @returns Whether the native SDK **accepted the event for delivery** —
+   *   not whether the collector received it. The event is queued locally and
+   *   posted later, so no return value from this call can attest to delivery;
+   *   a `true` here means only that the SDK took the event. A `false` is also
+   *   logged natively (logcat / os_log) so the rejection is visible.
+   */
   static logCustomEvent = async (eventName: string, values: Record<string, string | number | boolean>, level: number) => {
     let result = false
+    TLTRN.warnOnNestedValues('logCustomEvent', values);
     try {
       result = AcousticConnectRN.logCustomEvent(eventName, values, level);
     } catch (error: Error | any) {
@@ -209,8 +320,15 @@ class TLTRN {
     return result;
   };
 
+  /**
+   * Logs a custom event tied to a dialog.
+   *
+   * Same flat-values contract and same return-value meaning as
+   * {@link logCustomEvent} — it routes to the same native API.
+   */
   static logDialogCustomEvent = async (dialogId: string, eventName: string, values: Record<string, string | number | boolean>) => {
     let result = false
+    TLTRN.warnOnNestedValues('logDialogCustomEvent', values);
     try {
       result = AcousticConnectRN.logDialogCustomEvent(dialogId, eventName, values);
     } catch (error: Error | any) {
@@ -356,7 +474,10 @@ class TLTRN {
   static logTeal = async () => {
     try {
       TLTRN.isLoggingData = 1;
-      var res = await AcousticConnectRN.logScreenLayout(TLTRN.currentScreen, -1);
+      var res = await AcousticConnectRN.logScreenLayout(
+        TLTRN.currentScreen,
+        TLTRN.USE_CONFIGURED_CAPTURE_DELAY
+      );
       var dict = { ReactLayoutTime: TLTRN.totalRenderTime };
       var result = await AcousticConnectRN.logCustomEvent("ReactPlugin", dict, 1);
       if (TLTRN.displayDebug) {

package/src/components/Connect.tsx

@@ -8,7 +8,7 @@
 * prohibited.
 ********************************************************************************************/
 import React, { useCallback, useEffect, useRef, useState } from "react";
-import { View, StyleSheet, Platform } from "react-native";
+import { View, StyleSheet } from "react-native";
 import type { LayoutChangeEvent } from "react-native"; // Use type-only import for LayoutChangeEvent
 import TLTRN from '../TLTRN';
 
@@ -76,14 +76,13 @@ const Connect: React.FC<ConnectProps> = ({
     // ref is usable, then flip `navReady` to subscribe. The direct-child case
     // resolves on the first synchronous check (no polling, no warning). If the
     // ref never attaches within the grace window we warn once, as before.
-    // See CA-144314.
     useEffect(() => {
         // Reset readiness whenever the resolved ref changes. Without this, a
         // `navigationRef` prop swap leaves `navReady` stale-true, so the
         // subscription effect below re-runs and attaches `addListener` to the
         // old container (whose `.current` is still non-null mid-transition)
         // before the new ref is validated. Resetting forces re-validation
-        // through `isUsable()` before tracking re-enables. See CA-144314.
+        // through `isUsable()` before tracking re-enables.
         setNavReady(false);
 
         const isUsable = () =>
@@ -132,14 +131,28 @@ const Connect: React.FC<ConnectProps> = ({
 
         // Listen for the 'state' event to track navigation state changes
         const unsubscribeState = navigation.current.addListener("state", () => {
-            currentRoute.current = extractName(navigation) || navigation.current.getCurrentRoute()?.name;
+            // extractName resolves the focused route through the nested
+            // navigators itself, so there is no outer-level fallback to chain
+            // here — one used to be appended, which reported the tab name for
+            // every push inside that tab.
+            currentRoute.current = extractName(navigation);
 
-            if (Platform.OS === "ios" && currentRoute && currentRoute.current) {
-                TLTRN.logScreenViewPageName(currentRoute.current);
-            } else if (Platform.OS === "android") {
-                TLTRN.logScreenViewPageName(currentRoute.current);
-                TLTRN.logScreenLayout(currentRoute.current);
+            // Both platforms take the same path. iOS used to be excluded from
+            // the layout call, which left the wrapper with no layout trigger
+            // at all there: the one remaining bridge caller was TLTRN's
+            // render-settle timer, so a plain navigation captured nothing.
+            if (!currentRoute.current) {
+                return;
             }
+            TLTRN.logScreenViewPageName(currentRoute.current);
+            // Deliberately no delay argument. TLTRN then sends its
+            // "use the configured CaptureLayoutDelay" sentinel, so the capture
+            // is deferred past the transition. Passing 0 would select the
+            // native synchronous overload instead, which captures on the
+            // calling thread at the *start* of the transition — React
+            // Navigation fires 'state' before the animation runs — and makes
+            // CaptureLayoutDelay inert.
+            TLTRN.logScreenLayout(currentRoute.current);
         });
 
         // Cleanup listeners when the component unmounts or dependencies change
@@ -149,12 +162,9 @@ const Connect: React.FC<ConnectProps> = ({
     }, [navReady, navigation]);
 
     const onStartShouldSetResponderCapture = useCallback((event: any) => {
-        if (navigation?.current?.getCurrentRoute) {
-            currentRoute.current =
-                extractName(navigation) || navigation.current.getCurrentRoute()?.name;
-            if (currentRoute.current) {
-                TLTRN.logScreenViewPageName(currentRoute.current);
-            }
+        currentRoute.current = extractName(navigation);
+        if (currentRoute.current) {
+            TLTRN.logScreenViewPageName(currentRoute.current);
         }
         TLTRN.logClickEvent(event);
         return false; // Must remain false so events bubble to the host app's handlers
@@ -166,13 +176,18 @@ const Connect: React.FC<ConnectProps> = ({
         }
         initial.current = true;
 
-        if (navigation?.current?.getCurrentRoute) {
-            currentRoute.current = navigation.current.getCurrentRoute()?.name;
-            if (Platform.OS === "ios" && currentRoute.current) {
-                TLTRN.logScreenViewPageName(currentRoute.current);
-            } else if (Platform.OS === "android") {
-                TLTRN.logScreenLayout(currentRoute.current);
-            }
+        // Resolved through extractName like the other two triggers. This site
+        // used to read `getCurrentRoute()?.name` directly, so a `params.name`
+        // override was honoured on navigation but silently ignored for the
+        // first-paint screen — the same screen reported under two names.
+        currentRoute.current = extractName(navigation);
+        // Same unification as the 'state' listener above: the split sent
+        // only a screenview on iOS and only a layout on Android, so
+        // neither platform got both from the first-paint trigger. No delay
+        // argument, for the reason given there.
+        if (currentRoute.current) {
+            TLTRN.logScreenViewPageName(currentRoute.current);
+            TLTRN.logScreenLayout(currentRoute.current);
         }
         return true;
     }, [navigation]);
@@ -190,13 +205,121 @@ const Connect: React.FC<ConnectProps> = ({
     );
 };
 
+/**
+ * Walks a React Navigation state down to the deepest **focused** route.
+ *
+ * Nested navigators are the default architecture of production RN apps: a tab
+ * navigator whose tabs each hold a stack. The container's root state then
+ * describes only the outer level, and the route that the user is actually
+ * looking at lives in `routes[index].state`, recursively. Reading the outer
+ * level alone reports the *tab* name for every push inside that tab, so screen
+ * changes below the first level are invisible to analytics and replay.
+ *
+ * `index` can legitimately be absent on a partial/rehydrated state, in which
+ * case React Navigation treats the last route as focused — matched here.
+ *
+ * A depth cap guards against a malformed state whose nesting cycles; 32 is far
+ * past any real navigator tree.
+ */
+function findFocusedRoute(state: any): any {
+    let current = state;
+    let depth = 0;
+    while (current?.routes?.length && depth++ < 32) {
+        const index = current.index ?? current.routes.length - 1;
+        const route = current.routes[index];
+        if (!route?.state?.routes?.length) {
+            return route;
+        }
+        current = route.state;
+    }
+    return undefined;
+}
+
+/**
+ * Containers already reported by {@link warnExtractNameFailed}.
+ *
+ * Keyed by the container itself, so a ref that throws on every navigation
+ * produces one line rather than one per transition, while a genuinely
+ * different container still gets its own. A `WeakSet` holds no strong
+ * reference, so remembering a container cannot keep it alive.
+ */
+const extractNameErrorReported = new WeakSet<object>();
+
+/**
+ * Reports, once per container, that resolving the current route threw.
+ *
+ * A throw here is expected and harmless during teardown, which is why
+ * ``extractName`` swallows it. A ref that keeps throwing is a different
+ * matter: every screen view goes unnamed, and without a line here that looks
+ * exactly like a ref that never attached. One warning separates the two
+ * without flooding a listener that fires per navigation.
+ */
+function warnExtractNameFailed(container: unknown, error: unknown) {
+    if (typeof container === "object" && container !== null) {
+        if (extractNameErrorReported.has(container)) {
+            return;
+        }
+        extractNameErrorReported.add(container);
+    }
+    console.warn(
+        "Connect: could not resolve the current route — the navigation container ref threw. " +
+        "Screen views stay unnamed while this persists (harmless if the container is unmounting). " +
+        "Cause:",
+        error
+    );
+}
+
+/**
+ * The screen name to report for the navigation container's current position.
+ *
+ * Resolution order:
+ *
+ * 1. The focused route resolved from `getRootState()` by ``findFocusedRoute``.
+ *    Taking the state and walking it here — rather than trusting a single
+ *    accessor — keeps the wrapper correct regardless of whether the host app's
+ *    navigation library resolves nesting inside `getCurrentRoute()`, and works
+ *    for a custom container ref that exposes state but not that helper.
+ * 2. `getCurrentRoute()`, for refs that expose no `getRootState`.
+ *
+ * Either way `params.name` wins over the route's own `name` when the host app
+ * supplies it — the documented override for giving a route a human-readable
+ * analytics name. Only a non-empty string counts, so `params: { name: '' }`
+ * falls through to the route name instead of blanking the screenview.
+ *
+ * Returns `""` when nothing resolves, which both callers treat as "skip".
+ */
 function extractName(navigation: any): string {
-    const routeParams = navigation?.current?.getCurrentRoute?.()?.params;
-    if (routeParams) {
-        const { name } = routeParams;
-        return name ? name : navigation.current?.getCurrentRoute()?.name || "";
+    const container = navigation?.current;
+    if (!container) {
+        return "";
+    }
+
+    let route: any;
+    try {
+        route = findFocusedRoute(container.getRootState?.());
+    } catch (error) {
+        // A container mid-teardown can throw out of getRootState(). Screen
+        // naming is not worth taking the host app's navigation down for.
+        warnExtractNameFailed(container, error);
+        route = undefined;
+    }
+    if (!route) {
+        try {
+            route = container.getCurrentRoute?.();
+        } catch (error) {
+            warnExtractNameFailed(container, error);
+            route = undefined;
+        }
+    }
+    if (!route) {
+        return "";
+    }
+
+    const overridden = route.params?.name;
+    if (typeof overridden === "string" && overridden.length > 0) {
+        return overridden;
     }
-    return "";
+    return typeof route.name === "string" ? route.name : "";
 }
 
 export default Connect;

package/src/index.ts

@@ -41,4 +41,9 @@ try {
 }
 
 export { Connect, TLTRN, KeyboardListener, DialogListener, useDialogTracking, DialogDebugger, withAcousticAutoDialog }
+
+// Re-exported so callers can name a `logSignal` payload without importing
+// from `react-native-nitro-modules` — the spec aliases nitro's AnyMap only
+// because that is the one type nitrogen accepts for arbitrary JSON.
+export type { SignalValues } from './specs/react-native-acoustic-connect.nitro'
 export default AcousticConnectRN

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'
+ *
+ * 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,21 +149,138 @@ 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 SDK **accepted the event for delivery** — not
+     *   that the collector received it. Events are queued on device and posted
+     *   in batches later, so nothing this call can return attests to delivery
+     *   or to server-side acceptance. A `false` means the SDK rejected the
+     *   event outright and nothing was queued; the bridge also logs that to
+     *   logcat / os_log so it is visible without inspecting the return value.
+     */
     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 SDK **accepted the signal for delivery** — not
+     *   that the collector received it, and not that it passed server-side
+     *   schema validation. Signals are queued on device and posted later, so
+     *   nothing this call can return attests to delivery. A `false` means the
+     *   SDK rejected it and nothing was queued; the bridge logs that to
+     *   logcat / os_log.
+     *
+     * @remarks
+     * **Android version boundary — top-level numbers.** The Android SDK's
+     * `JsonUtil.getHashValues` gained a `Number` branch in Connect Android
+     * **11.0.24-beta**, so from that version a top-level numeric value is
+     * carried. Earlier versions serialised only `String`, `Boolean`,
+     * `JSONObject`, `JSONArray` and `byte[]` at the top level of the signal
+     * map and dropped a top-level number. Numbers nested *inside* an object
+     * or array were never affected, because the bridge builds those
+     * `JSONObject`/`JSONArray` values itself, and iOS has always carried
+     * top-level numbers normally. Both versions sit inside the
+     * `[11.0.11, 12.0.0)` range this package accepts, so nest the number if
+     * your integration pins a Connect Android version below 11.0.24-beta.
+     *
+     * @example Nested payload
+     * ```ts
+     * import AcousticConnectRN from 'react-native-acoustic-connect'
+     *
+     * 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
     logClickEvent(target: number, controlId: string): boolean
     logTextChangeEvent(target: number, controlId: string, text: string | null | undefined): boolean
+    /**
+     * Sets the logical screen name subsequent events are attributed to.
+     *
+     * Sets the name and nothing else — no screenview, no layout capture — on
+     * both platforms. `<Connect>` calls this on every touch so the click that
+     * follows lands on the right screen, so it has to stay cheap.
+     *
+     * Android used to route it through `Connect.resumeConnect`, which also
+     * emitted a screenview and captured a full layout, putting tens to hundreds
+     * of KB on the wire per tap where iOS sent none. Use `logScreenLayout` when
+     * a layout capture is what you want.
+     */
     setCurrentScreenName(logicalPageName: string): boolean
     logScreenViewContextLoad(logicalPageName: string | null | undefined, referrer:string | null | undefined): boolean
     logScreenViewContextUnload(logicalPageName: string | null | undefined, referrer:string | null | undefined): boolean
+    /**
+     * Captures the layout of the current screen.
+     *
+     * @param name  Screen name to associate with the capture.
+     * @param delay Milliseconds to wait before capturing — the same unit as
+     *   `CaptureLayoutDelay` in the layout config, on both platforms. A
+     *   negative value means "use the `CaptureLayoutDelay` configured for this
+     *   screen"; `0` captures immediately.
+     *
+     * Prefer `TLTRN.logScreenLayout`, which defaults to the configured delay.
+     *
+     * @returns For a `delay` of `0`, whether the capture itself succeeded. For
+     *   any positive or configured delay, only that the capture was
+     *   **scheduled** — the native deferred overload dispatches and returns
+     *   immediately, so a `true` says nothing about what the capture found
+     *   when it eventually ran. Failures after that point (no view controller
+     *   resolved, config gating the capture off) surface in logcat / os_log,
+     *   not here.
+     */
     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
+    /**
+     * 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 +304,62 @@ 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'
      *
+     * 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' }
+     * )
+     * ```
+     *
+     * @returns `true` if the SDK **accepted the identity signal for
+     *   delivery**. It does not mean the signal reached the collector, and it
+     *   does not mean the collector kept it — a schema-invalid signal (the
+     *   wrong method key above) is discarded server-side after resolving
+     *   `true` here. Never rejects. A `false` means the SDK rejected the call
+     *   locally, e.g. a blank identifier; the bridge logs that to logcat /
+     *   os_log.
      */
     logIdentity(
         identifierName: string,

package/Examples/SampleUI/.bundle/config

@@ -1,2 +0,0 @@
-BUNDLE_PATH: "vendor/bundle"
-BUNDLE_FORCE_RUBY_PLATFORM: 1