react-native-acoustic-connect-beta 19.0.14 → 19.0.16

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

@@ -62,6 +62,7 @@ import com.margelo.nitro.acousticconnectrn.PushPermissionResult
 import com.margelo.nitro.acousticconnectrn.Variant_Boolean_String_Double
 import com.margelo.nitro.acousticconnectrn.Variant_NullType_Boolean
 import com.margelo.nitro.acousticconnectrn.Variant_NullType_String
+import com.margelo.nitro.core.AnyMap
 import com.margelo.nitro.core.ArrayBuffer
 import com.margelo.nitro.core.NullType
 import com.margelo.nitro.core.Promise
@@ -70,6 +71,9 @@ import com.tl.uic.model.ScreenviewType
 import com.tl.uic.util.DialogUtil
 import com.tl.uic.util.LayoutUtil
 import com.tl.uic.util.keyboardview.KeyboardView
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
 import java.util.Objects
 
 
@@ -592,7 +596,8 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         value: Variant_Boolean_String_Double,
         moduleName: String
     ): Boolean {
-        val result = EOCore.updateConfig(key, value.toString(), EOCore.getLifecycleObject(moduleName))
+        val result =
+            EOCore.updateConfig(key, variantToString(value), EOCore.getLifecycleObject(moduleName))
         return result
     }
 
@@ -668,15 +673,21 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
     /**
      * Logs a signal with the specified values.
      *
-     * @param values A map of values associated with the signal.
+     * Takes an [AnyMap] rather than a map of Nitro variants so JS callers can
+     * send arbitrary JSON — nested objects and arrays included. See
+     * [toSignalPayload] for why the nesting has to be rebuilt as
+     * [JSONObject]/[JSONArray] rather than handed over as plain Kotlin
+     * collections.
+     *
+     * @param values The signal payload; objects, arrays and scalars are all carried through.
      * @param level  Set a custom log level to the event. This will override the configured log level for that event.
      * @return True if the operation was successful, false otherwise.
      */
     override fun logSignal(
-        values: Map<String, Variant_Boolean_String_Double>,
+        values: AnyMap,
         level: Double
     ): Boolean {
-        val result = Connect.logSignal(convertToMapAny(values), level.toInt())
+        val result = Connect.logSignal(toSignalPayload(values.toHashMap()), level.toInt())
         return result
     }
 
@@ -697,8 +708,11 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
      * @param identifierValue Identifier value, e.g. "user@example.com".
      * @param signalType Optional signal type; defaults to "loggedIn" when omitted.
      * @param additionalParameters Optional extra key/value pairs merged into the
-     *   signal. Defaults to `{ "registrationMethod": "email" }` only when null
-     *   (omitted); an explicit map — including an empty one — is used as-is.
+     *   signal. Defaults, only when null (omitted), to the method attribute the
+     *   resolved signal type requires — `{ "loginMethod": "email" }` for
+     *   `loggedIn`, `{ "registrationMethod": "email" }` otherwise (see
+     *   [defaultIdentityParameters]). An explicit map — including an empty one
+     *   — is used as-is.
      * @return A promise resolving to true if the signal was queued, false otherwise.
      */
     override fun logIdentity(
@@ -707,8 +721,8 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         signalType: String?,
         additionalParameters: Map<String, String>?
     ): Promise<Boolean> {
-        val params = additionalParameters ?: mapOf("registrationMethod" to "email")
         val resolvedSignalType = signalType ?: "loggedIn"
+        val params = additionalParameters ?: defaultIdentityParameters(resolvedSignalType)
         val result = params["url"]?.let { url ->
             Connect.logIdentificationEvent(
                 identifierName,
@@ -896,7 +910,10 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
      * Log Current Screen Layout using native side background thread.
      *
      * @param name  Page name or title e.g. "Login View Controller"; Must not be empty.
-     * @param delay The delay in milliseconds before logging the event.
+     * @param delay The delay in milliseconds before logging the event. A negative
+     *              value means "use the `CaptureLayoutDelay` configured for this
+     *              screen", which is what the JS wrapper sends when the caller
+     *              names no delay.
      * @return True if the operation was successful, false otherwise.
      */
     override fun logScreenLayout(name: String, delay: Double): Boolean {
@@ -907,13 +924,45 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
             result = logScreenLayout(
                 Objects.requireNonNull<Activity?>(getCurrentActivity()),
                 name,
-                if (delay.toInt() < 0) 300 else delay.toInt(),
+                resolveCaptureLayoutDelayMs(name, delay),
                 true
             )
         }
         return result
     }
 
+    /**
+     * Resolves the capture delay, in milliseconds, to apply for [name].
+     *
+     * A non-negative [delay] is the caller's explicit choice and passes
+     * straight through. A negative one defers to `CaptureLayoutDelay` in the
+     * layout config, which is what makes that setting reach the React Native
+     * wrapper at all — the wrapper used to hardcode 0 here, so the capture
+     * fired at the start of the screen transition and the configured value
+     * was inert.
+     *
+     * [LayoutUtil.getLayoutInfo] returns the merged rule for the screen: the
+     * global settings as a baseline with any per-screen rule applied over
+     * them, so this picks up either without re-implementing the precedence.
+     * It reads the config off disk, so a malformed or absent block falls back
+     * to [DEFAULT_CAPTURE_LAYOUT_DELAY_MS] rather than propagating a throw
+     * into a logging call.
+     */
+    internal fun resolveCaptureLayoutDelayMs(name: String, delay: Double): Int {
+        if (delay >= 0) {
+            return delay.toInt()
+        }
+        return try {
+            LayoutUtil.getLayoutInfo(name)
+                ?.optInt(CAPTURE_LAYOUT_DELAY_KEY, DEFAULT_CAPTURE_LAYOUT_DELAY_MS)
+                ?.coerceAtLeast(0)
+                ?: DEFAULT_CAPTURE_LAYOUT_DELAY_MS
+        } catch (e: Exception) {
+            Log.w(TAG, "Could not read $CAPTURE_LAYOUT_DELAY_KEY for \"$name\"; using ${DEFAULT_CAPTURE_LAYOUT_DELAY_MS}ms.", e)
+            DEFAULT_CAPTURE_LAYOUT_DELAY_MS
+        }
+    }
+
     /**
      * Logs a dialog show event with the specified dialog information.
      *
@@ -1187,7 +1236,7 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
             for (key in values.keys) {
                 val value = values[key]
                 if (value != null) {
-                    eventValues[key] = value.toString()
+                    eventValues[key] = variantToString(value)
                 }
             }
 
@@ -1200,9 +1249,42 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         return result
     }
 
+    /**
+     * Unwraps a Nitro variant to the underlying JS value it carries — a
+     * [Boolean], [String], or [Double].
+     *
+     * The generated `Variant_*` type is a sealed **data** class, so calling
+     * `toString()` on the variant itself yields the case wrapper
+     * (`"Second(value=pro)"`) instead of the value (`"pro"`). Every conversion
+     * that reads a variant must unwrap it first. Mirrors the iOS bridge's
+     * `ConnectRNParsing.convertVariantToAny`, keeping emitted payloads
+     * identical across platforms.
+     *
+     * @param value The variant to unwrap.
+     * @return The wrapped Boolean, String, or Double.
+     */
+    private fun unwrapVariant(value: Variant_Boolean_String_Double): Any =
+        value.match(first = { it }, second = { it }, third = { it })
+
+    /**
+     * 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.
+     *
+     * @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()
+
     /**
      * Converts a map of Variant_Boolean_String_Double to a HashMap<String?, String?>.
      *
+     * Values are unwrapped before stringifying (see [variantToString]).
+     *
      * @param values The map to be converted.
      * @return A HashMap<String?, String?> representation of the input map which library can use.
      */
@@ -1212,30 +1294,106 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         for (key in values.keys) {
             val value = values[key]
             if (value != null) {
-                map[key] = value.toString()
+                map[key] = variantToString(value)
             }
         }
         return map
     }
 
     /**
-     * Converts a map of Variant_Boolean_String_Double to a HashMap<String?, String?>.
+     * Converts an [AnyMap]-derived map into the payload `Connect.logSignal`
+     * expects, rebuilding nested structures as [JSONObject] / [JSONArray].
      *
-     * @param values The map to be converted.
-     * @return A HashMap<String?, String?> representation of the input map which library can use.
+     * The rebuild is mandatory, not cosmetic. The SDK serializes the signal
+     * through EOCore's `JsonUtil.getHashValues`, which walks the top-level
+     * entries and accumulates only `String`, `Boolean`, `JSONObject`,
+     * `JSONArray` and `ByteArray` — anything else is **silently dropped**. So
+     * a nested `Map`/`List` handed over as-is would vanish from the emitted
+     * signal without any error. Converting here is what makes nested payloads
+     * survive the wire.
+     *
+     * `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.
+     *
+     * A [JSONException] aborts the whole payload rather than escaping to the
+     * caller. Non-finite numbers are the case that raises it: `org.json`
+     * rejects them, and [toJsonValue] raises them explicitly so a top-level one
+     * behaves like a nested one. Either way a JS `Infinity` or `NaN` would
+     * otherwise throw straight out of `logSignal` and take the host app's call
+     * site down — unacceptable for an analytics SDK, and a behaviour change
+     * from the scalar-only bridge, which could not throw. Dropping the whole
+     * payload also matches iOS, where a single non-finite value fails
+     * `isValidJSONObject:` and the `signal` key is omitted entirely.
+     *
+     * @param values The map from [AnyMap.toHashMap].
+     * @return A HashMap the SDK's signal serializer can consume, or an empty
+     *   map if the payload could not be represented as JSON.
      */
     // internal (not private) so the unit tests in src/test can exercise it.
-    internal fun convertToMapAny(values: Map<String, Variant_Boolean_String_Double>): java.util.HashMap<String?, Any?>? {
-        val map = HashMap<String?, Any?>()
-        for (key in values.keys) {
-            val value = values[key]
-            if (value != null) {
-                map[key] = value
+    internal fun toSignalPayload(values: Map<String, Any?>): java.util.HashMap<String?, Any?> {
+        val map = HashMap<String?, Any?>(values.size)
+        try {
+            for ((key, value) in values) {
+                map[key] = toJsonValue(value)
             }
+        } catch (e: JSONException) {
+            Log.w(TAG, "[bridge] logSignal payload is not representable as JSON — dropping it: ${e.message}")
+            return HashMap()
         }
         return map
     }
 
+    /**
+     * Recursive helper for [toSignalPayload]. Maps Kotlin containers onto their
+     * `org.json` equivalents and leaves scalars alone.
+     *
+     * Nitro's JNI layer converts the whole tree to plain Java types before it
+     * reaches Kotlin — a JS object becomes a `HashMap`, a JS array an
+     * `ArrayList`, and scalars become `Double` / `Boolean` / `Long` / `String`
+     * — so there are no `AnyValue` wrappers left to unwrap here. [List] is
+     * therefore the branch a JS array actually takes; [Array] is handled too,
+     * to guard against a future Nitro representation change.
+     *
+     * @param value A value from an [AnyMap]-derived container.
+     * @return The `org.json`-compatible equivalent.
+     */
+    private fun toJsonValue(value: Any?): Any =
+        when (value) {
+            null -> JSONObject.NULL
+            is Map<*, *> -> JSONObject().apply {
+                for ((nestedKey, nestedValue) in value) {
+                    put(nestedKey.toString(), toJsonValue(nestedValue))
+                }
+            }
+            is Array<*> -> JSONArray().apply {
+                for (element in value) put(toJsonValue(element))
+            }
+            is List<*> -> JSONArray().apply {
+                for (element in value) put(toJsonValue(element))
+            }
+            // Checked here rather than left to `org.json`. A non-finite number
+            // nested in an object or array would be rejected by that container's
+            // `put`, but a TOP-LEVEL one is only ever handed to `HashMap.put`,
+            // which accepts anything — so without this the payload would reach
+            // the SDK and lose just that one key, while the nested case loses
+            // the whole payload. Raising it uniformly keeps the two consistent
+            // and matches iOS, where one non-finite value fails
+            // `isValidJSONObject:` for the entire signal.
+            is Double -> if (value.isFinite()) {
+                value
+            } else {
+                throw JSONException("non-finite number: $value")
+            }
+            else -> value
+        }
+
     /**
      * Gets the current activity from the ReactApplicationContext.
      *
@@ -1383,6 +1541,15 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         const val TAG = "AcousticConnectRN"
         const val DIALOG_CAPTURE_DELAY_MS = 500L // Configurable delay for dialog screenshot capture
 
+        /** Key holding the per-screen capture delay, in milliseconds, inside a layout-config rule. */
+        const val CAPTURE_LAYOUT_DELAY_KEY = "CaptureLayoutDelay"
+
+        /**
+         * Delay applied when the layout config names none. Matches the value the
+         * Connect SDK ships in its own `TealeafLayoutConfig.json`.
+         */
+        const val DEFAULT_CAPTURE_LAYOUT_DELAY_MS = 500
+
         // Class probed at runtime to detect whether the connect-push-fcm
         // transport artifact was included in the build (i.e. automatic mode,
         // where Connect's own FirebaseMessagingService is the PushReceived
@@ -1390,5 +1557,28 @@ class HybridAcousticConnectRN : HybridAcousticConnectRNSpec(),
         // by the connect-push-fcm artifact.
         private const val CONNECT_PUSH_FCM_PROBE_CLASS =
             "com.acoustic.connect.android.connectmod.push.services.fcm.FCMPushService"
+
+        /**
+         * Default `additionalParameters` for an identity signal, matched to the
+         * signal type the bridge will actually send.
+         *
+         * Connect's signal schema requires a *method* attribute on identity
+         * signals, and the required key differs per type: `loggedIn` requires
+         * `loginMethod`, `accountRegistered` requires `registrationMethod`.
+         * Supplying the wrong one fails schema validation and the signal is
+         * discarded, while [Connect.logIdentificationEvent] still reports
+         * success — so the caller sees nothing wrong. Before this mapping
+         * existed the bridge paired its `loggedIn` default with
+         * `registrationMethod`, which meant every defaulted identity call was
+         * silently dropped.
+         *
+         * Only consulted when the caller omits `additionalParameters`
+         * entirely; an explicitly-provided map is passed through untouched.
+         */
+        internal fun defaultIdentityParameters(signalType: String): Map<String, String> =
+            when (signalType) {
+                "loggedIn" -> mapOf("loginMethod" to "email")
+                else -> mapOf("registrationMethod" to "email")
+            }
     }
 }

package/ios/ConnectRNParsing.swift

@@ -104,6 +104,167 @@ internal enum ConnectRNParsing {
     // PushErrorInfo is a C++-backed nitro type, and this file is also
     // compiled into the UnitTests bundle, which builds without C++ interop.
 
+    /// `Connect` config keys that can carry an iOS layout-config block, in
+    /// **base-to-override order**: the shared block is the base, and the
+    /// iOS-specific block is layered on top of it.
+    ///
+    /// `layoutConfigIos` is what the shipped `ConnectConfig.json` template
+    /// writes, and the podspec copies the consumer's file into the resource
+    /// bundle verbatim (no key rename), so that is the key that actually
+    /// arrives at runtime. `layoutConfig` is the shared, cross-platform block:
+    /// a consumer can set a common baseline there and refine it per platform.
+    ///
+    /// `layoutConfigAndroid` is deliberately absent: applying it here would
+    /// push Android screen rules onto the iOS SDK.
+    static let layoutConfigKeys = ["layoutConfig", "layoutConfigIos"]
+
+    /// Entries of the layout-config block that map onto config-store overrides.
+    private static let layoutOverrideKeys = ["AutoLayout", "AppendMapIds"]
+
+    /// Recursively merges `override` onto `base`.
+    ///
+    /// Nested objects merge key by key, so a shared baseline survives a
+    /// platform block that only refines part of it. Every other value —
+    /// including arrays such as `MaskIdList` — is replaced outright rather than
+    /// concatenated, so a platform block can shorten a shared list.
+    static func deepMerging(_ base: [String: Any], _ override: [String: Any]) -> [String: Any] {
+        var merged = base
+        for (key, overrideValue) in override {
+            if let baseChild = merged[key] as? [String: Any],
+               let overrideChild = overrideValue as? [String: Any] {
+                merged[key] = deepMerging(baseChild, overrideChild)
+            } else {
+                merged[key] = overrideValue
+            }
+        }
+        return merged
+    }
+
+    /// Resolves the iOS layout-config block into the config-store overrides to
+    /// apply, keyed by the name the native SDK reads. `AutoLayout` becomes
+    /// `kConfigurableItemAutoLayout`, which `TLFAutoInstrumentationManger`
+    /// consumes for per-screen settings such as `ScreenShot` and
+    /// `CaptureScreenshotOn`.
+    ///
+    /// Both keys in ``layoutConfigKeys`` contribute: the shared `layoutConfig`
+    /// is applied first and `layoutConfigIos` is deep-merged over it, so an
+    /// iOS-specific value wins key by key while the shared baseline is kept for
+    /// everything the iOS block does not mention. A malformed block is logged
+    /// and skipped rather than aborting the rest of the resolution.
+    ///
+    /// Returns an empty dictionary when nothing is applicable, in which case
+    /// the caller applies nothing and the SDK keeps the defaults from its own
+    /// bundled `ConnectLayoutConfig.json`.
+    static func resolveLayoutOverrides(from connectData: [String: Any]) -> [String: Any] {
+        var block: [String: Any] = [:]
+        var contributing: [String] = []
+
+        for name in layoutConfigKeys {
+            guard let value = connectData[name] else { continue }
+            guard let candidate = value as? [String: Any] else {
+                configLog.error("Connect.\(name, privacy: .public) in ConnectConfig.json is not a JSON object. Ignoring it; iOS screen-capture settings fall back to the SDK defaults.")
+                continue
+            }
+            block = deepMerging(block, candidate)
+            contributing.append(name)
+        }
+
+        guard !contributing.isEmpty else { return [:] }
+
+        var overrides: [String: Any] = [:]
+        for name in layoutOverrideKeys {
+            if let override = block[name] {
+                overrides[name] = override
+            }
+        }
+
+        let sources = contributing.joined(separator: " <- ")
+        if overrides.isEmpty {
+            configLog.warning("Connect.\(sources, privacy: .public) carries no recognised override (expected AutoLayout and/or AppendMapIds). iOS screen-capture settings fall back to the SDK defaults.")
+        } else {
+            let applied = overrides.keys.sorted().joined(separator: ", ")
+            configLog.info("Applying layout overrides [\(applied, privacy: .public)] resolved from Connect.\(sources, privacy: .public)")
+        }
+        return overrides
+    }
+
+    // MARK: - Capture-layout delay
+
+    /// Config-store key holding the resolved `AutoLayout` block. Spelled out
+    /// rather than taken from Tealeaf's `kConfigurableItemAutoLayout` macro
+    /// because the bridge deliberately links against `Connect` only — see the
+    /// note on `ConnectConfigStore`. Same string either way.
+    static let autoLayoutConfigKey = "AutoLayout"
+
+    /// Key holding the per-screen capture delay inside an `AutoLayout` rule.
+    /// The value is in **milliseconds** — the auto-instrumentation path
+    /// dispatches with `NSEC_PER_MSEC`, and `TLFAutoLayoutConfig` names its
+    /// property `delayInMS`.
+    private static let captureLayoutDelayKey = "CaptureLayoutDelay"
+
+    /// Rule names holding the settings that apply to every screen. The second
+    /// is the legacy spelling; the native SDK reads whichever is present, so
+    /// this does too.
+    private static let globalScreenSettingsKeys = ["GlobalScreenSettings", "IBMGlobalScreenSettings"]
+
+    /// Delay applied when nothing in the resolved `AutoLayout` block names one.
+    /// Matches `TLFAutoInstrumentationManger`'s own fallback.
+    static let defaultCaptureLayoutDelayMs: Double = 500
+
+    /// Resolves the `CaptureLayoutDelay` (milliseconds) that applies to
+    /// `name`, from the `AutoLayout` block the native SDK holds in its config
+    /// store.
+    ///
+    /// Resolution mirrors `TLFAutoInstrumentationManger`: the global rule
+    /// supplies the baseline, and a rule named after the screen overrides it.
+    /// The JS wrapper looks the screen up by its React Navigation route name,
+    /// which is the key `ConnectConfig.json`'s `layoutConfig`/`layoutConfigIos`
+    /// blocks are written against.
+    ///
+    /// Returns ``defaultCaptureLayoutDelayMs`` when the block is missing,
+    /// malformed, or names no delay — never a value that would make the caller
+    /// silently skip the deferral it asked for.
+    static func captureLayoutDelayMs(for name: String, in autoLayout: [String: Any]?) -> Double {
+        guard let autoLayout else { return defaultCaptureLayoutDelayMs }
+
+        if let screenDelay = delayValue(in: autoLayout[name]) {
+            return screenDelay
+        }
+        for key in globalScreenSettingsKeys {
+            if let globalDelay = delayValue(in: autoLayout[key]) {
+                return globalDelay
+            }
+        }
+        return defaultCaptureLayoutDelayMs
+    }
+
+    /// Pulls `CaptureLayoutDelay` out of one `AutoLayout` rule. `nil` means
+    /// "this rule says nothing about the delay", which is what lets the caller
+    /// fall through to the next source rather than treating a missing rule as
+    /// an explicit zero.
+    private static func delayValue(in rule: Any?) -> Double? {
+        guard let rule = rule as? [String: Any] else { return nil }
+        guard let raw = rule[captureLayoutDelayKey] else { return nil }
+        if let number = raw as? NSNumber { return max(0, number.doubleValue) }
+        if let text = raw as? String, let parsed = Double(text) { return max(0, parsed) }
+        configLog.warning("\(captureLayoutDelayKey, privacy: .public) is set but is not a number. Ignoring it.")
+        return nil
+    }
+
+    /// Whether `ConnectConfig.json` supplies an `AutoLayout` block at all.
+    ///
+    /// Equivalent to asking whether ``resolveLayoutOverrides(from:)`` would
+    /// return an `AutoLayout` override — `deepMerging` only ever adds keys, so
+    /// the merged block carries `AutoLayout` exactly when some contributing
+    /// block does — but silent, and cheap enough to run at construction. The
+    /// resolver logs which sources it applied; calling it twice would print
+    /// that summary twice.
+    static func suppliesAutoLayout(_ connectData: [String: Any]) -> Bool {
+        return layoutConfigKeys.contains { name in
+            (connectData[name] as? [String: Any])?[autoLayoutConfigKey] != nil
+        }
+    }
+
     /// Maps the JS-facing module name to the config store's module name
     /// ("Connect" → "TLFCoreModule").
     static func storeModuleName(for moduleName: String) -> String {
@@ -130,6 +291,51 @@ internal enum ConnectRNParsing {
         return result
     }
 
+    /// Normalises a dictionary produced by `AnyMap.toDictionary()` into one
+    /// that `NSJSONSerialization.isValidJSONObject:` accepts, which is the
+    /// only gate `CTSignalMessage` applies before embedding the payload.
+    ///
+    /// Two things need fixing up. `AnyMap` models JS `null` as a Swift `nil`,
+    /// and a dictionary holding `Optional.none` is not JSON-representable —
+    /// `NSNull` is. And the nesting is optional-typed all the way down
+    /// (`[String: Any?]` / `[Any?]`), so the walk has to be recursive rather
+    /// than a single top-level pass. Values that are already scalars pass
+    /// through untouched, so a flat payload converts to exactly what the
+    /// previous scalar-only bridge produced.
+    ///
+    /// Deliberately takes plain Swift collections rather than `AnyMap`: this
+    /// file is compiled into the UnitTests bundle, which builds without C++
+    /// interop and therefore cannot see nitro's `AnyMap`/`AnyValue` types.
+    /// The `AnyMap` unwrapping stays in `HybridAcousticConnectRN`.
+    ///
+    /// - Parameter input: dictionary from `AnyMap.toDictionary()`.
+    /// - Returns: the same structure with optionals resolved.
+    static func jsonSafeDictionary(_ input: [String: Any?]) -> [String: Any] {
+        var result = [String: Any](minimumCapacity: input.count)
+        for (key, value) in input {
+            result[key] = jsonSafeValue(value)
+        }
+        return result
+    }
+
+    /// Recursive helper for ``jsonSafeDictionary(_:)``. Maps `nil` to `NSNull`
+    /// and rebuilds nested dictionaries/arrays; every other value — `String`,
+    /// `Double`, `Int64`, `Bool` — is already JSON-representable and is
+    /// returned as-is.
+    ///
+    /// - Parameter value: a value from an `AnyMap`-derived container.
+    /// - Returns: a JSON-representable equivalent.
+    static func jsonSafeValue(_ value: Any?) -> Any {
+        guard let value else { return NSNull() }
+        if let nested = value as? [String: Any?] {
+            return jsonSafeDictionary(nested)
+        }
+        if let array = value as? [Any?] {
+            return array.map { jsonSafeValue($0) }
+        }
+        return value
+    }
+
     static func convertVariantToAny(_ variant: Variant_Bool_String_Double) -> Any {
         switch variant {
         case .first(let boolValue):
@@ -141,6 +347,29 @@ internal enum ConnectRNParsing {
         }
     }
 
+    /// Default `additionalParameters` for an identity signal, matched to the
+    /// signal type the bridge will actually send.
+    ///
+    /// Connect's signal schema requires a *method* attribute on identity
+    /// signals, and the required key differs per type: `loggedIn` requires
+    /// `loginMethod`, `accountRegistered` requires `registrationMethod`.
+    /// Supplying the wrong one fails schema validation and the signal is
+    /// discarded, while `identity.log` still reports success — so the caller
+    /// sees nothing wrong. Before this mapping existed the bridge paired its
+    /// `loggedIn` default with `registrationMethod`, which meant every
+    /// defaulted identity call was silently dropped.
+    ///
+    /// Only consulted when the caller omits `additionalParameters` entirely;
+    /// an explicitly-provided map is passed through untouched.
+    static func defaultIdentityParameters(for signalType: String) -> [String: String] {
+        switch signalType {
+        case "loggedIn":
+            return ["loginMethod": "email"]
+        default:
+            return ["registrationMethod": "email"]
+        }
+    }
+
     static func logLevel(from level: Double) -> kConnectMonitoringLevelType {
         let intValue: Int = Int(level)
         if intValue == 0 {