react-native-acoustic-connect-beta 19.0.18 → 19.0.20

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 19.0.20 (2026-09-09)
+
+### Reverts
+
+* Revert "Beta ReactNativeConnect build: 18.0.36" ([609ad7d](https://github.com/aipoweredmarketer/react-native-acoustic-connect-beta/commit/609ad7d3244ec06f27dced5864d40585c5b3c9cf))
+## 19.0.19 (2026-09-08)
+
+### Reverts
+
+* Revert "Beta ReactNativeConnect build: 18.0.36" ([609ad7d](https://github.com/aipoweredmarketer/react-native-acoustic-connect-beta/commit/609ad7d3244ec06f27dced5864d40585c5b3c9cf))
 ## 19.0.18 (2026-09-07)
 
 ### Reverts

package/README.md

@@ -396,6 +396,26 @@ for details.
 
 ## API reference
 
+> **What the logging methods' `boolean` means.** Every `log*` method returns
+> whether the native SDK **accepted the event for delivery** — never whether
+> the collector received it, and never whether the collector kept it. Events
+> are queued on device and posted in batches later, so no return value from
+> these calls can attest to delivery, and a server-side rejection (a signal
+> that fails schema validation, say) happens long after you have already been
+> told `true`. Treat the value as "the SDK took this", and use the collector or
+> the platform log as the source of truth for what shipped.
+>
+> A `false` means the SDK rejected the call outright and nothing was queued.
+> The bridge also writes that to `logcat` (tag `AcousticConnectRN`) and
+> `os_log` (subsystem `com.acoustic.AcousticConnectRN`, category `bridge`), so
+> a rejection is visible without inspecting return values you would otherwise
+> never read.
+>
+> `logScreenLayout` is weaker still: with the configured delay — the normal
+> case — a `true` means only that the capture was **scheduled**. What the
+> capture found when it eventually ran, and whether it produced a layout
+> message at all, is reported in the platform log only.
+
 ### `AcousticConnectRN.enable(): boolean`
 
 Re-enables the SDK after a prior `disable()`. Reads all configuration from
@@ -463,6 +483,13 @@ AcousticConnectRN.logSignal(pageView, 1)
 > AcousticConnectRN.logSignal({ cart: { items: 3 } }, 1) // both platforms
 > AcousticConnectRN.logSignal({ items: 3 }, 1)           // iOS only
 > ```
+>
+> The Android bridge logs a warning naming the keys the SDK is about to
+> discard, so the loss shows up in `logcat` instead of only in a dashboard
+> that never fills in. It does not coerce the value: making the number survive
+> as a JSON string would replace a missing field with a differently-typed one
+> and diverge from iOS in a new way. The fix belongs in the Android SDK's
+> serializer.
 
 ### `AcousticConnectRN.logCustomEvent(eventName, values, level): boolean`
 
@@ -472,6 +499,20 @@ string values end to end, so there is no native route for nested JSON; widening
 it would preserve the nesting on iOS and silently drop it on Android. Use
 `logSignal` when the payload needs structure.
 
+TypeScript will reject a nested value, but types are erased at runtime — a
+payload built from an API response or widened through `any` still reaches the
+bridge nested, gets reshaped by the native SDK, and returns `true`. The wrapper
+logs a `console.warn` naming the offending keys when that happens (once per
+call site, in dev and in production; the payload itself is passed through
+unchanged). If you see it, move the payload to `logSignal`.
+
+Numbers are rendered the same way on both platforms — a JS `2` arrives as `2`,
+not `2.0`. Note the remaining difference in *type*: because the Android path is
+string-typed, an Android custom-event number lands on the wire as a JSON string
+(`"2"`) where iOS sends a JSON number (`2`). `logSignal` carries native types on
+both platforms; reach for it when a dashboard or Composer rule compares the
+value numerically.
+
 ### Push configuration (`ConnectConfig.json`)
 
 | Field | Type | Default | Semantics |
@@ -560,6 +601,41 @@ layout config:
 > clicks, and custom events still flow. It only drops the image data, which is
 > what a subscription without session replay has no consumer for.
 
+#### `NumberOfWebViews` turns off iOS layout capture — leave it at `0`
+
+`AutoLayout` rules accept a `NumberOfWebViews` key. On iOS, any value greater
+than zero marks the screens that rule covers as web-view screens, and the SDK's
+automatic layout capture is skipped for a web-view screen. Its effect is not
+limited to screens that actually host a `WebView`: the value is read as a
+declaration about the rule, not a count that gets verified.
+
+The trap is where it is usually set. `GlobalScreenSettings` is the rule that
+applies to **every** screen with no more specific rule of its own, and React
+Native screens are all in that position — they are hosted by the same generic
+container class, so no per-screen native rule matches them. So a single
+`"NumberOfWebViews": 1` under `GlobalScreenSettings` switches off
+auto-instrumented layout capture for the entire app on iOS, including screens
+with no web content at all:
+
+```json
+{
+  "Connect": {
+    "layoutConfigIos": {
+      "AutoLayout": {
+        "GlobalScreenSettings": { "NumberOfWebViews": 0 }
+      }
+    }
+  }
+}
+```
+
+Screen views, clicks, and custom events are unaffected — the symptom is layout
+messages going missing while everything else keeps arriving, which reads like a
+capture failure rather than a setting. Keep `NumberOfWebViews` at `0`, the value
+every shipped template uses. To stand layout capture down deliberately, set
+`CaptureLayoutOn: 0` on the rule instead — it is the key that means that, and it
+leaves `NumberOfWebViews` free to describe the screen.
+
 #### Capture timing (`CaptureLayoutDelay`)
 
 `AutoLayout.GlobalScreenSettings.CaptureLayoutDelay` is how long, in
@@ -601,6 +677,58 @@ default, chosen so both platforms behave the same; the native SDKs' own bundled
 defaults differ from each other and are tuned for the lifecycle trigger rather
 than the React Navigation one.
 
+#### Where screen-view and layout messages come from, and how to reduce duplicates
+
+The two message kinds have different sources, and they differ per platform:
+
+**Screen views (one source per platform).** On Android, the `<Connect>` wrapper
+is the *only* source — it emits on React Navigation's `state` event. On iOS,
+the native SDK's auto-instrumentation is the *only* source — it emits when a
+screen's view controller reports its appearance. The wrapper never emits a
+screen view on iOS; its role there is to hand the current *route name* to the
+native SDK (which is what makes messages read `Checkout` rather than a native
+container class) and to drive referrer chaining across transitions.
+
+Duplicate screen views observed on iOS are therefore not two sources
+overlapping — they are the single native source firing more than once when the
+same screen's view controller reports several appearances for one transition.
+They inflate event volumes and skew per-screen counts; they do not lose data.
+There is no configuration key that collapses them today; a native-side dedupe
+is under investigation. Do not try to solve it by removing the wrapper: on iOS
+that costs route-based names and referrer chaining, and on Android it removes
+screen views entirely. A same-name filter in the wrapper would not help either
+— the wrapper is not the emitter on iOS, and such a filter would swallow
+legitimate repeats like a stack pushing the same screen name twice.
+
+**Layouts (two sources on iOS).** With automatic layout capture enabled in
+config, an iOS transition can produce two layout messages: one from the
+wrapper's `logScreenLayout` call and one from the native auto-instrumentation.
+Control it from config, on the native side that has the duplicate:
+
+```json
+{
+  "Connect": {
+    "layoutConfigIos": {
+      "AutoLayout": {
+        "GlobalScreenSettings": { "CaptureLayoutOn": 0 }
+      }
+    }
+  }
+}
+```
+
+`CaptureLayoutOn: 0` stands the **native** automatic layout capture down and
+leaves the wrapper's route-named captures as the single source. Set it per
+screen rather than globally if only some screens are noisy. Screen views,
+clicks, and custom events are unaffected by this key.
+
+If you would rather keep the native captures and have the wrapper stay out of
+the way, omit `navigationRef` and do not rely on `<Connect>` for screen naming
+— but expect native container class names in place of your route names.
+
+Measure before changing either default: the volume depends on your navigator
+structure, and both defaults are what every shipped sample uses.
+
 ### `<Connect>` props
 
 | Prop | Type | Required | Description |

package/android/src/main/assets/ConnectBasicConfig.properties

@@ -1,4 +1,4 @@
-#Mon Sep 07 11:29:39 GMT 2026
+#Wed Sep 09 11:26:30 GMT 2026
 UseWhiteList=true
 PrintScreen=3
 UseRandomSample=false

package/android/src/main/java/com/acousticconnectrn/HybridAcousticConnectRN.kt

@@ -579,7 +579,12 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         value: Double,
         moduleName: String
     ): Boolean {
-        val result = EOCore.updateConfig(key, value.toString(), EOCore.getLifecycleObject(moduleName))
+        // Rendered through formatJsNumber, not Double.toString: EOCore stores
+        // config items as strings, and a JS 0 spelled "0.0" is not the same
+        // token as the "0" the JSON config files carry, so a consumer setting
+        // a whole-number item at runtime wrote a value that no longer matched
+        // what the same key looks like on iOS (a native number) or on disk.
+        val result = EOCore.updateConfig(key, formatJsNumber(value), EOCore.getLifecycleObject(moduleName))
         return result
     }
 
@@ -667,7 +672,7 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         level: Double
     ): Boolean {
         val result = Connect.logCustomEvent(eventName, convertToMap(values), level.toInt())
-        return result
+        return warnIfRejected(result, "logCustomEvent", eventName)
     }
 
     /**
@@ -688,6 +693,38 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         level: Double
     ): Boolean {
         val result = Connect.logSignal(toSignalPayload(values.toHashMap()), level.toInt())
+        return warnIfRejected(result, "logSignal")
+    }
+
+    /**
+     * Surfaces a `false` returned by a native logging call, and passes it
+     * through unchanged.
+     *
+     * The bridge's boolean means "the SDK accepted this for delivery", never
+     * "the collector received it" — nothing on the device knows the latter. But
+     * the *accepted* half was itself invisible: a `false` propagated to JS as a
+     * bare return value that the wrapper's callers almost never inspect, with
+     * nothing in logcat. Callers reporting "the event never arrived" had no way
+     * to tell a rejected call from a delivery problem. One line at warn level
+     * distinguishes them.
+     *
+     * Deliberately does not change the return value or throw: an analytics
+     * bridge must not turn a rejected event into an app-visible failure.
+     *
+     * @param result The value the native call returned.
+     * @param api    Name of the bridge method, for the log line.
+     * @param detail Optional extra identifier, e.g. an event name.
+     * @return [result], unchanged.
+     */
+    private fun warnIfRejected(result: Boolean, api: String, detail: String? = null): Boolean {
+        if (!result) {
+            val suffix = if (detail != null) " ($detail)" else ""
+            Log.w(
+                TAG,
+                "[bridge] $api$suffix: the Connect SDK did not accept the event; nothing was queued " +
+                    "for delivery. Check that the SDK is enabled and the payload is valid."
+            )
+        }
         return result
     }
 
@@ -737,7 +774,11 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
             signalType = resolvedSignalType,
             additionalParameters = params
         )
-        return Promise.resolved(result)
+        // An identity signal that the SDK accepts can still be rejected
+        // downstream by schema validation — a mismatched method attribute has
+        // cost a customer 22 signals while every call reported success. The
+        // bridge cannot see that; it can at least report the half it does see.
+        return Promise.resolved(warnIfRejected(result, "logIdentity", resolvedSignalType))
     }
 
     /**
@@ -969,16 +1010,61 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         // crash on an ordinary screen change.
         val activity = getCurrentActivity()
         if (activity != null && LayoutUtil.canCaptureUserEvents(null, name)) {
-            result = logScreenLayout(
+            result = logAutomaticScreenLayout(
                 activity,
                 name,
-                resolveCaptureLayoutDelayMs(name, delay),
-                true
+                resolveCaptureLayoutDelayMs(name, delay)
             )
         }
         return result
     }
 
+    /**
+     * Captures the layout of [activity] as an *automatic* capture — the kind
+     * the wrapper triggers itself, on navigation or behind a dialog — rather
+     * than a manual `logScreenLayout` API call from the host app.
+     *
+     * Every wrapper-initiated capture must go through here, because the
+     * distinction is what makes the configured `ScreenShot` value reach the
+     * native screenshot gate at all:
+     *
+     * - `Connect`'s four-argument overload hardcodes `manualLog = true`, and
+     *   the native gate reads the configured `ScreenShot` only on the
+     *   `manualLog = false` branch. Passing a literal `true` for the screenshot
+     *   flag — which every wrapper call site used to do — therefore took the
+     *   manual branch unconditionally, so `ScreenShot: false` could not be
+     *   honoured from config and a full-page image shipped in every layout
+     *   message regardless. Hence the five-argument overload, with
+     *   `manualLog = false`.
+     * - [LayoutUtil.canTakeScreenShot] resolves the same merged layout rule the
+     *   native automatic path uses (global settings as a baseline, any
+     *   per-screen rule applied over them). It is preferred over reading
+     *   `ScreenShot` directly because it is `has()`-guarded: a per-screen rule
+     *   that omits the key defaults to capturing rather than throwing a
+     *   `JSONException`, which higher up is swallowed and costs the whole
+     *   layout message. Its first argument may be null while the page name is
+     *   non-empty, the same pattern as `canCaptureUserEvents(null, name)`.
+     *
+     * Note `CaptureScreenshotOn` is not consulted anywhere on Android: its only
+     * native reader has no callers, so `ScreenShot` is the one wired-up switch.
+     *
+     * [activity] is nullable to match the five-argument overload; callers that
+     * need a non-null one check or assert before calling.
+     */
+    private fun logAutomaticScreenLayout(
+        activity: Activity?,
+        name: String,
+        delayMs: Int
+    ): Boolean {
+        return logScreenLayout(
+            activity,
+            name,
+            delayMs,
+            false,
+            LayoutUtil.canTakeScreenShot(null, name)
+        )
+    }
+
     /**
      * Resolves the capture delay, in milliseconds, to apply for [name].
      *
@@ -1047,12 +1133,12 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
                         } else {
                             Log.v(TAG, "Warning: Could not find dialog object for $dialogId after delay")
                             // Fallback to regular screen layout capture
-                            logScreenLayout(Objects.requireNonNull<Activity?>(getCurrentActivity()), dialogTitle, 0, true)
+                            logAutomaticScreenLayout(Objects.requireNonNull<Activity?>(getCurrentActivity()), dialogTitle, 0)
                         }
                     } catch (e: Exception) {
                         Log.v(TAG, "Error in delayed dialog capture: ${e.message}")
                         // Fallback to regular screen layout capture
-                        logScreenLayout(Objects.requireNonNull<Activity?>(getCurrentActivity()), dialogTitle, 0, true)
+                        logAutomaticScreenLayout(Objects.requireNonNull<Activity?>(getCurrentActivity()), dialogTitle, 0)
                     }
                 }, DIALOG_CAPTURE_DELAY_MS) // Use configurable delay
 
@@ -1071,7 +1157,7 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
                     }
                 } else {
                     // Default fallback
-                    result = logScreenLayout(Objects.requireNonNull<Activity?>(getCurrentActivity()), dialogTitle, 300, true)
+                    result = logAutomaticScreenLayout(Objects.requireNonNull<Activity?>(getCurrentActivity()), dialogTitle, 300)
                 }
             }
         } catch (e: Exception) {
@@ -1318,15 +1404,56 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
      * Unwraps a Nitro variant (see [unwrapVariant]) and renders it as a string,
      * for the SDK entry points that take `HashMap<String, String>` payloads.
      *
-     * Booleans render as `"true"`/`"false"` and numbers via Kotlin's [Double]
-     * formatting (a JS `2` arrives as `2.0` and renders `"2.0"`); strings pass
-     * through unchanged.
+     * Booleans render as `"true"`/`"false"`, strings pass through unchanged,
+     * and numbers go through [formatJsNumber] so they read the way the same
+     * JS value reads on iOS.
      *
      * @param value The variant to stringify.
      * @return The wrapped value's string form.
      */
     private fun variantToString(value: Variant_Boolean_String_Double): String =
-        unwrapVariant(value).toString()
+        when (val unwrapped = unwrapVariant(value)) {
+            is Double -> formatJsNumber(unwrapped)
+            else -> unwrapped.toString()
+        }
+
+    /**
+     * Renders a JS number the way JS itself — and therefore the iOS bridge —
+     * renders it: `2` stays `"2"`, `2.5` stays `"2.5"`.
+     *
+     * Every JS number crosses Nitro as a [Double], so a JS `2` arrives as
+     * `2.0`, and Kotlin's [Double.toString] spells that `"2.0"`. iOS hands the
+     * same value to the SDK as a native number, which `NSJSONSerialization`
+     * writes as `2`. The result was a cross-platform payload split on any
+     * whole number — `"seats": "2.0"` on Android against `"seats": 2` on iOS —
+     * which breaks dashboards and Composer rules that compare the two.
+     * Dropping the trailing `.0` closes the *textual* half of that gap.
+     *
+     * It does not close the *type* half on the custom-event path: the SDK's
+     * `logCustomEvent` chain is typed `HashMap<String, String>` end to end, so
+     * an Android custom-event number is a JSON string (`"2"`) where iOS sends a
+     * JSON number (`2`). Only `logSignal` carries native types on Android, and
+     * that path deliberately does not come through here — see [toSignalPayload].
+     *
+     * Integral values are rendered through [Long] only below 2^53, which spans
+     * every integer JS itself represents exactly; beyond that the [Double] form
+     * is kept rather than inventing digits a `Long` round-trip would imply.
+     * Non-finite values keep Kotlin's spelling (`"NaN"`, `"Infinity"`) — there
+     * is no JSON representation to match, and stringifying is strictly safer
+     * than throwing out of an analytics call.
+     *
+     * @param value The number to render.
+     * @return Its string form, without a trailing `.0` for whole numbers.
+     */
+    internal fun formatJsNumber(value: Double): String {
+        if (!value.isFinite()) {
+            return value.toString()
+        }
+        if (value == Math.floor(value) && Math.abs(value) < 9007199254740992.0) {
+            return value.toLong().toString()
+        }
+        return value.toString()
+    }
 
     /**
      * Converts a map of Variant_Boolean_String_Double to a HashMap<String?, String?>.
@@ -1363,12 +1490,26 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
      * `null` becomes [JSONObject.NULL] rather than a Kotlin `null`, which
      * `org.json` requires for an explicit JSON `null`.
      *
-     * Known limitation: a **top-level** numeric value is still dropped, because
-     * `getHashValues` has no `Number` branch and the bridge cannot influence
-     * that walk. Numbers nested inside an object or array are unaffected — the
-     * enclosing [JSONObject]/[JSONArray] is built here, so `org.json`
-     * serializes them normally. iOS carries top-level numbers fine; this is an
-     * SDK-side asymmetry, pre-dating this conversion.
+     * Known limitation: a **top-level** numeric value is still dropped, and
+     * cannot be rescued from here. `Signal.getJSON()` serializes the payload
+     * through EOCore's `JsonUtil.getHashValues`, whose `instanceof` ladder has
+     * no `Number` branch, so the entry is skipped with no error. Numbers nested
+     * inside an object or array are unaffected — the enclosing
+     * [JSONObject]/[JSONArray] is built here, so `org.json` serializes them
+     * normally. iOS carries top-level numbers fine; this is an SDK-side
+     * asymmetry, pre-dating this conversion.
+     *
+     * Two non-fixes, so they are not attempted again: coercing the number to a
+     * [String] would make it survive as a JSON string, diverging from iOS's
+     * JSON number in a *new* way and silently changing the shape of data
+     * already-shipping clients receive; and there is no `org.json` wrapper that
+     * `getHashValues` accepts and that serializes as a bare number, so the
+     * shape cannot be preserved either. The real fix is a `Number` branch in
+     * `getHashValues` (Android SDK).
+     *
+     * What this method does do is [warnAboutDroppedTopLevelNumbers] — name the
+     * keys the SDK is about to discard, so the loss is visible in logcat
+     * instead of silent.
      *
      * A [JSONException] aborts the whole payload rather than escaping to the
      * caller. Non-finite numbers are the case that raises it: `org.json`
@@ -1395,9 +1536,44 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
             Log.w(TAG, "[bridge] logSignal payload is not representable as JSON — dropping it: ${e.message}")
             return HashMap()
         }
+        warnAboutDroppedTopLevelNumbers(map)
         return map
     }
 
+    /**
+     * Logs a warning naming the top-level numeric keys that the SDK's signal
+     * serializer will discard (see [toSignalPayload] for why it does).
+     *
+     * The point is purely to stop the loss being silent. Before this, a JS
+     * `logSignal({ orderTotal: 24.99 })` returned `true`, emitted a type-21
+     * message, and simply had no `orderTotal` in it — indistinguishable, from
+     * the caller's side, from a signal that arrived intact. The same call on
+     * iOS carries the value, so a cross-platform dashboard shows the metric
+     * populated on one platform and empty on the other with nothing anywhere
+     * to explain it.
+     *
+     * Iterates the already-converted map so it reflects exactly what is handed
+     * to the SDK. Booleans and strings are not mentioned: `getHashValues`
+     * accumulates both.
+     *
+     * @param payload The converted payload, as returned to `logSignal`.
+     */
+    private fun warnAboutDroppedTopLevelNumbers(payload: Map<String?, Any?>) {
+        val dropped = payload.entries
+            .filter { it.value is Number }
+            .mapNotNull { it.key }
+        if (dropped.isEmpty()) {
+            return
+        }
+        Log.w(
+            TAG,
+            "[bridge] logSignal: top-level numeric value(s) ${dropped.sorted()} will be dropped by the " +
+                "Android SDK's signal serializer, which accumulates only strings, booleans and nested " +
+                "JSON. iOS sends them. Nest the value under an object to carry it on both platforms, " +
+                "e.g. { cart: { total: 24.99 } } instead of { total: 24.99 }."
+        )
+    }
+
     /**
      * Recursive helper for [toSignalPayload]. Maps Kotlin containers onto their
      * `org.json` equivalents and leaves scalars alone.