react-native-acoustic-connect 19.0.9 → 19.0.28

package/lib/module/components/Connect.js

@@ -10,7 +10,7 @@
 * prohibited.
 ********************************************************************************************/
 import React, { useCallback, useEffect, useRef, useState } from "react";
-import { View, StyleSheet, Platform } from "react-native";
+import { View, StyleSheet } from "react-native";
 // Use type-only import for LayoutChangeEvent
 import TLTRN from '../TLTRN';
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -56,14 +56,13 @@ const Connect = ({
   // 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 = () => !!navigation && !!navigation.current && typeof navigation.current.addListener === "function" && typeof navigation.current.getCurrentRoute === "function";
     if (isUsable()) {
@@ -99,13 +98,28 @@ const Connect = ({
 
     // Listen for the 'state' event to track navigation state changes
     const unsubscribeState = navigation.current.addListener("state", () => {
-      currentRoute.current = extractName(navigation) || navigation.current.getCurrentRoute()?.name;
-      if (Platform.OS === "ios" && currentRoute && currentRoute.current) {
-        TLTRN.logScreenViewPageName(currentRoute.current);
-      } else if (Platform.OS === "android") {
-        TLTRN.logScreenViewPageName(currentRoute.current);
-        TLTRN.logScreenLayout(currentRoute.current);
+      // 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);
+
+      // 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
@@ -114,11 +128,9 @@ const Connect = ({
     };
   }, [navReady, navigation]);
   const onStartShouldSetResponderCapture = useCallback(event => {
-    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
@@ -128,13 +140,19 @@ const Connect = ({
       return false;
     }
     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]);
@@ -147,15 +165,115 @@ const Connect = ({
     }) : children
   });
 };
+
+/**
+ * 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) {
+  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();
+
+/**
+ * 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, error) {
+  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) {
-  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;
+  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;
 const styles = StyleSheet.create({

package/lib/module/components/Connect.js.map

@@ -1 +1 @@
-{"version":3,"names":["React","useCallback","useEffect","useRef","useState","View","StyleSheet","Platform","TLTRN","jsx","_jsx","Connect","children","captureKeyboardEvents","captureDialogEvents","navigationRef","child","childProvidedRef","props","ref","internalRef","navigation","shouldInjectRef","isValidElement","currentRoute","undefined","initial","navReady","setNavReady","interceptKeyboardEvents","interceptDialogEvents","isUsable","current","addListener","getCurrentRoute","attempts","POLL_INTERVAL_MS","MAX_ATTEMPTS","timer","poll","console","warn","setTimeout","clearTimeout","unsubscribeState","extractName","name","OS","logScreenViewPageName","logScreenLayout","onStartShouldSetResponderCapture","event","logClickEvent","onLayout","_event","style","styles","connect_main","cloneElement","routeParams","params","create","flex"],"sourceRoot":"../../../src","sources":["components/Connect.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["React","useCallback","useEffect","useRef","useState","View","StyleSheet","TLTRN","jsx","_jsx","Connect","children","captureKeyboardEvents","captureDialogEvents","navigationRef","child","childProvidedRef","props","ref","internalRef","navigation","shouldInjectRef","isValidElement","currentRoute","undefined","initial","navReady","setNavReady","interceptKeyboardEvents","interceptDialogEvents","isUsable","current","addListener","getCurrentRoute","attempts","POLL_INTERVAL_MS","MAX_ATTEMPTS","timer","poll","console","warn","setTimeout","clearTimeout","unsubscribeState","extractName","logScreenViewPageName","logScreenLayout","onStartShouldSetResponderCapture","event","logClickEvent","onLayout","_event","style","styles","connect_main","cloneElement","findFocusedRoute","state","depth","routes","length","index","route","extractNameErrorReported","WeakSet","warnExtractNameFailed","container","error","has","add","getRootState","overridden","params","name","create","flex"],"sourceRoot":"../../../src","sources":["components/Connect.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/index.js

@@ -35,5 +35,10 @@ try {
   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 };
+
+// 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 default AcousticConnectRN;
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["NitroModules","Connect","KeyboardListener","DialogListener","useDialogTracking","withAcousticAutoDialog","DialogDebugger","TLTRN","AcousticConnectRN","createHybridObject","error","Error","String"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,YAAY,QAAQ,4BAA4B;AAEzD,OAAOC,OAAO,MAAM,sBAAsB;AAC1C,OAAOC,gBAAgB,MAAM,0BAA0B;AACvD,OAAOC,cAAc,MAAM,wBAAwB;AACnD,OAAOC,iBAAiB,MAAM,2BAA2B;AACzD,SAASC,sBAAsB,QAAQ,gCAAgC;AACvE,OAAOC,cAAc,MAAM,wBAAwB;AACnD,OAAOC,KAAK,MAAM,SAAS;;AAE3B;AACA;AACA;AACA;AACA;AACA;AACA,IAAIC,iBAAwC;AAC5C,IAAI;EACFA,iBAAiB,GAAGR,YAAY,CAACS,kBAAkB,CAAwB,mBAAmB,CAAC;AACjG,CAAC,CAAC,OAAOC,KAAK,EAAE;EACd,MAAM,IAAIC,KAAK,CACb,0EAA0E,GACxE,4EAA4E,GAC5E,4EAA4E,GAC5E,kFAAkF,GAClF,mBAAmBC,MAAM,CAACF,KAAK,CAAC,EACpC,CAAC;AACH;AAEA,SAAST,OAAO,EAAEM,KAAK,EAAEL,gBAAgB,EAAEC,cAAc,EAAEC,iBAAiB,EAAEE,cAAc,EAAED,sBAAsB;AACpH,eAAeG,iBAAiB","ignoreList":[]}
+{"version":3,"names":["NitroModules","Connect","KeyboardListener","DialogListener","useDialogTracking","withAcousticAutoDialog","DialogDebugger","TLTRN","AcousticConnectRN","createHybridObject","error","Error","String"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,YAAY,QAAQ,4BAA4B;AAEzD,OAAOC,OAAO,MAAM,sBAAsB;AAC1C,OAAOC,gBAAgB,MAAM,0BAA0B;AACvD,OAAOC,cAAc,MAAM,wBAAwB;AACnD,OAAOC,iBAAiB,MAAM,2BAA2B;AACzD,SAASC,sBAAsB,QAAQ,gCAAgC;AACvE,OAAOC,cAAc,MAAM,wBAAwB;AACnD,OAAOC,KAAK,MAAM,SAAS;;AAE3B;AACA;AACA;AACA;AACA;AACA;AACA,IAAIC,iBAAwC;AAC5C,IAAI;EACFA,iBAAiB,GAAGR,YAAY,CAACS,kBAAkB,CAAwB,mBAAmB,CAAC;AACjG,CAAC,CAAC,OAAOC,KAAK,EAAE;EACd,MAAM,IAAIC,KAAK,CACb,0EAA0E,GACxE,4EAA4E,GAC5E,4EAA4E,GAC5E,kFAAkF,GAClF,mBAAmBC,MAAM,CAACF,KAAK,CAAC,EACpC,CAAC;AACH;AAEA,SAAST,OAAO,EAAEM,KAAK,EAAEL,gBAAgB,EAAEC,cAAc,EAAEC,iBAAiB,EAAEE,cAAc,EAAED,sBAAsB;;AAEpH;AACA;AACA;;AAEA,eAAeG,iBAAiB","ignoreList":[]}

package/lib/typescript/src/TLTRN.d.ts

@@ -35,13 +35,97 @@ declare class TLTRN {
     static interceptKeyboardEvents: (enable: boolean) => void;
     static logScreenViewPageName: (name: string | undefined) => boolean;
     static logScreenViewContextLoad: (name: string, prevName: string) => boolean;
-    static logScreenLayout: (name: string | undefined) => boolean;
+    /**
+     * 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: number;
+    /**
+     * 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) => boolean;
     static logClickEvent: (event: any) => Promise<boolean>;
     static logTextChangeEvent: (target: number, controlId: string, text: string, _ariaLabel: string) => Promise<boolean>;
+    /**
+     * Keys already warned about, so a call site inside a render or a list loop
+     * warns once rather than on every pass.
+     */
+    static warnedNestedValueSites: 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: number;
+    /**
+     * 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>) => void;
+    /**
+     * 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: (eventName: string, values: Record<string, string | number | boolean>, level: number) => Promise<boolean>;
     static logDialogShowEvent: (dialogId: string, dialogTitle: string, dialogType: string) => Promise<boolean>;
     static logDialogDismissEvent: (dialogId: string, dismissReason: string) => Promise<boolean>;
     static logDialogButtonClickEvent: (dialogId: string, buttonText: string, buttonIndex: number) => Promise<boolean>;
+    /**
+     * 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: (dialogId: string, eventName: string, values: Record<string, string | number | boolean>) => Promise<boolean>;
     static eventListenerRegistered: boolean;
     static eventListenerUnsubscribe: (() => void) | null;

package/lib/typescript/src/TLTRN.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TLTRN.d.ts","sourceRoot":"","sources":["../../../src/TLTRN.ts"],"names":[],"mappings":"AAAA;;;;;;;;6FAQ6F;;AAmC7F,cAAM,KAAK;IACT,MAAM,CAAC,aAAa,SACgD;IACpE,MAAM,CAAC,uBAAuB,SAAK;IACnC,MAAM,CAAC,eAAe,SAAK;IAC3B,MAAM,CAAC,iBAAiB,SAAK;IAC7B,MAAM,CAAC,SAAS,SAAK;IACrB,MAAM,CAAC,cAAc,SAAK;IAC1B,MAAM,CAAC,kBAAkB,SAAK;IAC9B,MAAM,CAAC,aAAa,SAAK;IACzB,MAAM,CAAC,YAAY,UAAS;IAE5B,MAAM,CAAC,OAAO;;;;QAIZ;;WAEG;;QAKH;;WAEG;;MAQH;IAEF,MAAM,CAAC,IAAI,yBAA0B,MAAM,4BAA4B,OAAO,UAQ5E;IAEF,MAAM,CAAC,uBAAuB,WAAY,OAAO,UAE/C;IAEF,MAAM,CAAC,qBAAqB,SAAU,MAAM,GAAG,SAAS,aAQtD;IAEF,MAAM,CAAC,wBAAwB,SAAU,MAAM,YAAY,MAAM,aAQ/D;IAEF,MAAM,CAAC,eAAe,SAAU,MAAM,GAAG,SAAS,aAShD;IAEF,MAAM,CAAC,aAAa,UAAiB,GAAG,sBA+BtC;IAEF,MAAM,CAAC,kBAAkB,WAAkB,MAAM,aAAa,MAAM,QAAQ,MAAM,cAAc,MAAM,sBAYpG;IAEF,MAAM,CAAC,cAAc,cAAqB,MAAM,UAAU,OAAO,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,sBAQhH;IAGF,MAAM,CAAC,kBAAkB,aAAoB,MAAM,eAAe,MAAM,cAAc,MAAM,sBAQ1F;IAEF,MAAM,CAAC,qBAAqB,aAAoB,MAAM,iBAAiB,MAAM,sBAQ3E;IAEF,MAAM,CAAC,yBAAyB,aAAoB,MAAM,cAAc,MAAM,eAAe,MAAM,sBAQjG;IAEF,MAAM,CAAC,oBAAoB,aAAoB,MAAM,aAAa,MAAM,UAAU,OAAO,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,sBAQzH;IAGF,MAAM,CAAC,uBAAuB,UAAS;IACvC,MAAM,CAAC,wBAAwB,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAQ;IAE5D,MAAM,CAAC,qBAAqB,WAAY,OAAO,UA0B7C;IAEF,MAAM,CAAC,cAAc,YAAa,GAAG,UAqEnC;IAEF,MAAM,CAAC,SAAS,aA6Bd;IAEF,MAAM,CAAC,OAAO,sBAsBZ;CACH;AAGD,eAAe,KAAK,CAAC"}
+{"version":3,"file":"TLTRN.d.ts","sourceRoot":"","sources":["../../../src/TLTRN.ts"],"names":[],"mappings":"AAAA;;;;;;;;6FAQ6F;;AAmC7F,cAAM,KAAK;IACT,MAAM,CAAC,aAAa,SACgD;IACpE,MAAM,CAAC,uBAAuB,SAAK;IACnC,MAAM,CAAC,eAAe,SAAK;IAC3B,MAAM,CAAC,iBAAiB,SAAK;IAC7B,MAAM,CAAC,SAAS,SAAK;IACrB,MAAM,CAAC,cAAc,SAAK;IAC1B,MAAM,CAAC,kBAAkB,SAAK;IAC9B,MAAM,CAAC,aAAa,SAAK;IACzB,MAAM,CAAC,YAAY,UAAS;IAE5B,MAAM,CAAC,OAAO;;;;QAIZ;;WAEG;;QAKH;;WAEG;;MAQH;IAEF,MAAM,CAAC,IAAI,yBAA0B,MAAM,4BAA4B,OAAO,UAQ5E;IAEF,MAAM,CAAC,uBAAuB,WAAY,OAAO,UAE/C;IAEF,MAAM,CAAC,qBAAqB,SAAU,MAAM,GAAG,SAAS,aAQtD;IAEF,MAAM,CAAC,wBAAwB,SAAU,MAAM,YAAY,MAAM,aAQ/D;IAEF;;;;;OAKG;IACH,MAAM,CAAC,4BAA4B,SAAM;IAEzC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,eAAe,SAAU,MAAM,GAAG,SAAS,YAAY,MAAM,aAYlE;IAEF,MAAM,CAAC,aAAa,UAAiB,GAAG,sBA+BtC;IAEF,MAAM,CAAC,kBAAkB,WAAkB,MAAM,aAAa,MAAM,QAAQ,MAAM,cAAc,MAAM,sBAYpG;IAEF;;;OAGG;IACH,MAAM,CAAC,sBAAsB,cAAqB;IAElD;;;;;;;;;OASG;IACH,MAAM,CAAC,6BAA6B,SAAO;IAE3C;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,kBAAkB,QAAS,MAAM,UAAU,OAAO,MAAM,EAAE,OAAO,CAAC,UAyBvE;IAEF;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,cAAc,cAAqB,MAAM,UAAU,OAAO,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,sBAShH;IAGF,MAAM,CAAC,kBAAkB,aAAoB,MAAM,eAAe,MAAM,cAAc,MAAM,sBAQ1F;IAEF,MAAM,CAAC,qBAAqB,aAAoB,MAAM,iBAAiB,MAAM,sBAQ3E;IAEF,MAAM,CAAC,yBAAyB,aAAoB,MAAM,cAAc,MAAM,eAAe,MAAM,sBAQjG;IAEF;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,aAAoB,MAAM,aAAa,MAAM,UAAU,OAAO,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,sBASzH;IAGF,MAAM,CAAC,uBAAuB,UAAS;IACvC,MAAM,CAAC,wBAAwB,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAQ;IAE5D,MAAM,CAAC,qBAAqB,WAAY,OAAO,UA0B7C;IAEF,MAAM,CAAC,cAAc,YAAa,GAAG,UAqEnC;IAEF,MAAM,CAAC,SAAS,aA6Bd;IAEF,MAAM,CAAC,OAAO,sBAyBZ;CACH;AAGD,eAAe,KAAK,CAAC"}

package/lib/typescript/src/components/Connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Connect.d.ts","sourceRoot":"","sources":["../../../../src/components/Connect.tsx"],"names":[],"mappings":"AAAA;;;;;;;;6FAQ6F;AAC7F,OAAO,KAAmD,MAAM,OAAO,CAAC;AAKxE,UAAU,YAAY;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;CACxC;AAED,QAAA,MAAM,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,YAAY,CA8JnC,CAAC;AAWF,eAAe,OAAO,CAAC"}
+{"version":3,"file":"Connect.d.ts","sourceRoot":"","sources":["../../../../src/components/Connect.tsx"],"names":[],"mappings":"AAAA;;;;;;;;6FAQ6F;AAC7F,OAAO,KAAmD,MAAM,OAAO,CAAC;AAKxE,UAAU,YAAY;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;CACxC;AAED,QAAA,MAAM,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,YAAY,CA6KnC,CAAC;AAuHF,eAAe,OAAO,CAAC"}

package/lib/typescript/src/index.d.ts

@@ -20,5 +20,6 @@ import DialogDebugger from './utils/DialogDebugger';
 import TLTRN from './TLTRN';
 declare let AcousticConnectRN: AcousticConnectRNSpec;
 export { Connect, TLTRN, KeyboardListener, DialogListener, useDialogTracking, DialogDebugger, withAcousticAutoDialog };
+export type { SignalValues } from './specs/react-native-acoustic-connect.nitro';
 export default AcousticConnectRN;
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;6FAW6F;AAG7F,OAAO,KAAK,EAAE,iBAAiB,IAAI,qBAAqB,EAAE,MAAM,6CAA6C,CAAA;AAC7G,OAAO,OAAO,MAAM,sBAAsB,CAAA;AAC1C,OAAO,gBAAgB,MAAM,0BAA0B,CAAA;AACvD,OAAO,cAAc,MAAM,wBAAwB,CAAA;AACnD,OAAO,iBAAiB,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,cAAc,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,MAAM,SAAS,CAAA;AAQ3B,QAAA,IAAI,iBAAiB,EAAE,qBAAqB,CAAA;AAa5C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,CAAA;AACtH,eAAe,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;6FAW6F;AAG7F,OAAO,KAAK,EAAE,iBAAiB,IAAI,qBAAqB,EAAE,MAAM,6CAA6C,CAAA;AAC7G,OAAO,OAAO,MAAM,sBAAsB,CAAA;AAC1C,OAAO,gBAAgB,MAAM,0BAA0B,CAAA;AACvD,OAAO,cAAc,MAAM,wBAAwB,CAAA;AACnD,OAAO,iBAAiB,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,cAAc,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,MAAM,SAAS,CAAA;AAQ3B,QAAA,IAAI,iBAAiB,EAAE,qBAAqB,CAAA;AAa5C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,CAAA;AAKtH,YAAY,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAC/E,eAAe,iBAAiB,CAAA"}

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

@@ -1,8 +1,33 @@
-import { type HybridObject } from 'react-native-nitro-modules';
+import { type AnyMap, type HybridObject } from 'react-native-nitro-modules';
 export type KeyValueObject = {
     placeholder: string;
     [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';
 /**
  * Structured error describing an APNs / permission failure.
@@ -107,8 +132,86 @@ export interface AcousticConnectRN extends HybridObject<{
     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-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;
@@ -117,10 +220,36 @@ export interface AcousticConnectRN extends HybridObject<{
     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;
     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;
     /**
      * Logs a user identity so the current device/session can be associated with
@@ -143,23 +272,62 @@ export interface AcousticConnectRN extends HybridObject<{
      *   `'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' }
+     * )
+     * ```
+     *
+     * @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, identifierValue: string, signalType?: string, additionalParameters?: Record<string, string>): Promise<boolean>;
     /**