@booleanmaths/booleanmaths-rn-sdk 0.1.1 → 0.3.0

package/BooleanmathsRnSdk.podspec

@@ -10,11 +10,37 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
+  # No platform override needed. BooleanMathsSDK 1.0.1 lowered its own floor to
+  # 15.1, which is exactly React Native's min_ios_version_supported — pinning a
+  # higher floor here would push it onto every consuming app.
   s.platforms    = { :ios => min_ios_version_supported }
   s.source       = { :git => "https://github.com/medront/react-native-booleanmaths-sdk.git", :tag => "v#{s.version}" }
 
+  # Globs `swift` so ios/BMBooleanMathsBridge.swift is compiled. That shim is
+  # mandatory, not stylistic: BooleanMaths is a pure Swift `@MainActor final
+  # class` with no Objective-C surface, so the .mm cannot reach it directly.
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  # Does not match the generated BooleanmathsRnSdk-Swift.h, which the .mm needs.
   s.private_header_files = "ios/**/*.h"
 
+  s.swift_version = "5.9"
+
+  # `~> 1.0.1`, deliberately not `~> 1.0`: 1.0.0 is still published on Trunk
+  # carrying an iOS 17.0 deployment target, and resolving to it would break the
+  # install for any app below iOS 17.
+  s.dependency "BooleanMathsSDK", "~> 1.0.1"
+
+  # Mirrors Android's BuildConfig.WRAPPER_VERSION, which is read from
+  # package.json so the reported wrapper_version cannot drift from the published
+  # npm version — s.version is that same value. Consumed by the .mm as an
+  # Objective-C preprocessor define; it does not reach Swift.
+  #
+  # $(inherited) is load-bearing: without it this replaces the pod target's
+  # inherited defines instead of appending, dropping DEBUG, RCT_NEW_ARCH_ENABLED
+  # and the FOLLY_* flags that React Native's own xcconfig sets.
+  s.pod_target_xcconfig = {
+    "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) BMRN_WRAPPER_VERSION=\\\"#{s.version}\\\""
+  }
+
   install_modules_dependencies(s)
 end

package/README.md

@@ -5,42 +5,90 @@ and attribution.
 
 This package is a thin TurboModule bridge over the native
 [`com.booleanmaths:bm-sdk`](https://central.sonatype.com/artifact/com.booleanmaths/bm-sdk)
-Android SDK.
+Android SDK and the
+[`BooleanMathsSDK`](https://cocoapods.org/pods/BooleanMathsSDK) iOS SDK.
 
----
+**One import, one API, both platforms.** There are no platform-specific entry
+points — `import { BooleanMaths } from '@booleanmaths/booleanmaths-rn-sdk'` and
+call the same methods everywhere.
 
-## ⚠️ Platform support
+---
 
-> **There is no BooleanMaths iOS SDK yet.** The native SDK is published for
-> **Android only**. On iOS (and on web) this package installs and builds
-> normally, but **every SDK call is a no-op and no events are tracked**.
+## Platform support
 
 | Platform | Native SDK | Behaviour |
 | :------- | :--------- | :-------- |
-| Android  | ✅ `com.booleanmaths:bm-sdk:1.0.8` | Fully functional |
-| iOS      | ❌ not published | Silent no-op, **never crashes** |
+| Android  | ✅ `com.booleanmaths:bm-sdk:1.0.9` | Fully functional |
+| iOS      | ✅ `BooleanMathsSDK 1.0.1` | Event tracking fully functional — see below |
 | Web      | ❌ not published | Silent no-op, **never crashes** |
 
+### What iOS supports
+
+Event tracking is complete and at parity with Android. Attribution features
+are not — they are deferred to a later release, so their absence is scope
+rather than a bug.
+
+| Feature | Android | iOS |
+| :------ | :-----: | :-: |
+| `initialize()` | ✅ | ✅ |
+| `trackEvent()` with nested properties | ✅ | ✅ |
+| `wrapper_type` / `wrapper_version` on every event | ✅ | ✅ |
+| Automatic `app_opened` | ✅ | ✅ |
+| Automatic `FirstOpen` (once per install) | ✅ | ✅ — but with no attribution payload, see below |
+| Visitor ID and 30-minute session handling | ✅ | ✅ |
+| Durable on-device queue surviving app restarts | ✅ | ✅ |
+| Automatic flush when the app backgrounds | ✅ | ✅ |
+| `getHelloMessage()` bridge smoke test | ✅ | ✅ |
+| **Deep links / universal links** (`DeepLinkClick`) | ✅ | ❌ |
+| **Push-notification attribution** (`NotificationClick`) | ✅ | ❌ |
+| **`handleIntent()` / `handleNotificationIntent()`** | ✅ | ❌ no-op |
+| **Install attribution** on `FirstOpen` | ✅ Play Install Referrer | ❌ `data` is `{}` |
+
+Notes on the iOS gaps:
+
+- **`handleIntent()` is safe to call on iOS.** It reaches a native no-op and
+  logs one dev-mode notice. Shared code does not need to branch on platform.
+- **`FirstOpen` still fires on iOS**, once per install — it just carries no
+  campaign payload. `data` is `{}` (present but empty), so the wire shape will
+  not change when Apple Search Ads attribution lands.
+- On iOS there is **no `DeepLinkClick` or `NotificationClick` event at all**,
+  and consequently no `data.attribution` block on subsequent events.
+- **`flush()` is not exposed to JavaScript** on either platform. The iOS SDK
+  flushes automatically on `willResignActive` / `didBecomeActive`; it will be
+  exposed only once Android has an equivalent, so it can ship as a genuinely
+  cross-platform API.
+- macOS and tvOS are out of scope. The native SDK compiles for them; this
+  wrapper targets iOS only.
+
 ### Why it does not crash
 
-Two independent guards, so a missing iOS SDK can never take your app down:
+Two independent guards, so an unsupported platform or an incomplete native
+install can never take your app down:
 
 1. **JavaScript gate.** `BooleanMaths` checks `Platform.OS` against an
-   allowlist (currently `['android']`) and returns before touching the native
+   allowlist (`['android', 'ios']`) and returns before touching the native
    bridge. It also verifies the TurboModule actually resolved, which covers a
-   broken or incomplete native install.
-2. **Native backstop.** iOS still ships a real TurboModule
-   ([`ios/BooleanmathsRnSdk.mm`](ios/BooleanmathsRnSdk.mm)) whose methods are
-   no-ops. So even a direct call into the bridge is harmless.
+   broken or incomplete native install — most often a JS install without a
+   native rebuild.
+2. **Native backstop.** Every native call is wrapped so failures are logged
+   rather than thrown into JavaScript
+   ([`safely()`](android/src/main/java/com/booleanmathsrnsdk/BooleanmathsRnSdkModule.kt)
+   on Android, `BMSafely()` in
+   [`ios/BooleanmathsRnSdk.mm`](ios/BooleanmathsRnSdk.mm)). Analytics should
+   never crash the host app.
+
+On web the JavaScript gate is the whole story: a separate no-op implementation
+([`src/BooleanMaths.tsx`](src/BooleanMaths.tsx)) is resolved by the bundler, so
+shared code can call the SDK unconditionally without platform checks.
 
 In development (`__DEV__`) you get **one** console warning per app launch, not
 one per call.
 
-### The fix: gate your own analytics code
+### Optionally gate your own analytics code
 
 Calling the SDK unconditionally is safe — you do not *need* to branch. But if
-you want to avoid dead work, skip the dev warning, or show different UI, branch
-on `isSupported`:
+you want to avoid dead work on web, skip the dev warning, or show different UI,
+branch on `isSupported`:
 
 ```ts
 import { BooleanMaths } from '@booleanmaths/booleanmaths-rn-sdk';
@@ -48,21 +96,12 @@ import { BooleanMaths } from '@booleanmaths/booleanmaths-rn-sdk';
 if (BooleanMaths.isSupported) {
   BooleanMaths.initialize(API_KEY, PIXEL_ID);
 } else {
-  // Fall back to another analytics provider on iOS, or do nothing.
+  // Web, or a native install that needs rebuilding. Fall back or do nothing.
 }
 ```
 
-`isSupported` is a plain boolean, evaluated at module load — cheap to read as
-often as you like.
-
-### When the iOS SDK ships
-
-Two changes, no API break for consumers:
-
-1. Add the iOS dependency to [`BooleanmathsRnSdk.podspec`](BooleanmathsRnSdk.podspec)
-   and implement the method bodies in [`ios/BooleanmathsRnSdk.mm`](ios/BooleanmathsRnSdk.mm).
-2. Add `'ios'` to `SUPPORTED_PLATFORMS` in
-   [`src/BooleanMaths.native.tsx`](src/BooleanMaths.native.tsx).
+`isSupported` is `true` on Android and iOS. It is a plain boolean, evaluated at
+module load — cheap to read as often as you like.
 
 ---
 
@@ -78,14 +117,17 @@ Then rebuild the native app — a Metro reload is **not** enough:
 
 ```sh
 npx react-native run-android
+# and/or
+cd ios && pod install && cd .. && npx react-native run-ios
 ```
 
 ### Requirements
 
 - React Native **0.80+** with the **New Architecture** enabled (this is a
   TurboModule)
-- Android **minSdkVersion 24** or higher (the native SDK requires it)
-- `compileSdkVersion 36`, Java 17
+- **Android:** `minSdkVersion` 24 or higher (the native SDK requires it),
+  `compileSdkVersion 36`, Java 17
+- **iOS:** deployment target **15.1** or higher, and **Xcode 16+**
 
 ### Android
 
@@ -98,20 +140,38 @@ To pin a different native SDK version, set this in your app's **root**
 ```gradle
 buildscript {
     ext {
-        BooleanmathsRnSdk_bmSdkVersion = "1.0.8"
+        BooleanmathsRnSdk_bmSdkVersion = "1.0.9"
     }
 }
 ```
 
 ### iOS
 
-Run `pod install` as usual. This installs the no-op stub described above — it
-compiles and links, it just does not track anything.
+Autolinking picks the module up; run `pod install` to pull in the native SDK.
 
 ```sh
 cd ios && pod install
 ```
 
+That resolves `BooleanMathsSDK` from CocoaPods Trunk. Points worth knowing:
+
+- **Minimum deployment target is iOS 15.1**, matching React Native's own floor,
+  so adopting this SDK does not raise your app's minimum iOS version.
+- **The pod is pinned to `~> 1.0.1`,** deliberately not `~> 1.0`. Version 1.0.0
+  is still published with an iOS 17.0 floor, and resolving to it would break
+  the install for apps below iOS 17. Confirm your `Podfile.lock` shows
+  `BooleanMathsSDK (1.0.1)` or newer.
+- **The SDK ships as a closed-source, vendored *dynamic* XCFramework.**
+  CocoaPods embeds and re-signs it with your app's identity. If you use
+  `use_frameworks!`, both `:linkage => :static` and `:linkage => :dynamic`
+  are supported.
+- **No privacy manifest work needed.** The SDK bundles its own
+  `PrivacyInfo.xcprivacy` inside the XCFramework, so App Store
+  privacy-manifest requirements are covered by the pod.
+- **Xcode 16+ is required.** The SDK's `.swiftinterface` is emitted at Swift 6.
+  Library evolution is enabled, so it is not pinned to the exact Xcode that
+  built it — but the toolchain must understand Swift 6.
+
 ---
 
 ## Usage
@@ -146,34 +206,66 @@ ignored.
 
 ### `BooleanMaths.initialize(apiKey, pixelId): void`
 
-Initializes the native SDK. Also registers this wrapper with the native SDK so
-every event carries `wrapper_type: "react-native"` and the wrapper version, and
-forwards the launch intent (see [Deep links](#deep-links-and-notification-attribution)).
+Initializes the native SDK. Also registers this wrapper with the native SDK
+**before** initializing, so that even the automatic `FirstOpen` and `app_opened`
+events emitted during initialization already carry
+`wrapper_type: "react-native"` and the wrapper version. That version is read
+from `package.json` on both platforms, so it cannot drift from the published npm
+version.
+
+On Android it additionally forwards the launch intent (see
+[Deep links](#deep-links-and-notification-attribution)); there is no iOS
+equivalent.
 
 ### `BooleanMaths.trackEvent(name, properties?): void`
 
 Records a custom event. `properties` defaults to `{}` and may contain strings,
 numbers, booleans, nested objects, and arrays.
 
+### `BooleanMaths.handleIntent(): void`
+
+**Android only.** Forwards the current Activity's intent to the native SDK so
+ad deep links, app links and push-notification campaign data are attributed.
+Safe to call repeatedly — the native SDK de-duplicates intents it has already
+seen.
+
+This is the single entry point for every kind of launch intent; native SDK
+1.0.9 unified them behind one method.
+
+**A no-op on iOS**, and safe to call there — it logs one dev-mode notice and
+returns. The reason is scope, not platform support: intents are an Android
+concept, and iOS deep links / universal links are deferred to a later release.
+You do not need to branch on platform before calling it.
+
 ### `BooleanMaths.handleNotificationIntent(): void`
 
-**Android only** (no-op elsewhere). Forwards the current Activity's intent to
-the native SDK so deep-link and notification campaign data is attributed. Safe
-to call repeatedly — the native SDK de-duplicates intents it has already seen.
+Deprecated alias of `handleIntent()`, kept so existing callers keep working.
+It calls straight through to the same native `handleIntent`, so there is no
+behavioural difference — prefer `handleIntent()` in new code.
 
 ### `BooleanMaths.getHelloMessage(): string | null`
 
 Bridge smoke test. Returns the native SDK's hello string, or `null` where there
-is no native SDK.
+is no native SDK. The string comes from the native SDK itself on both platforms
+(not from this wrapper), so a correct value also proves the native artifact
+actually linked — which on iOS is the quickest way to confirm the XCFramework
+was embedded.
 
 ### `BooleanMaths.isSupported: boolean`
 
-`true` only where a real native SDK is linked. Currently Android only.
+`true` only where a real native SDK is linked — Android and iOS. `false` on
+web, and on any platform where the native module failed to resolve (typically a
+JS install without a native rebuild).
 
 ---
 
 ## Deep links and notification attribution
 
+> **Android only.** This entire section does not apply to iOS, where
+> `handleIntent()` is a no-op and no `DeepLinkClick` / `NotificationClick`
+> events are produced. The code below is still safe to run unchanged on iOS —
+> the calls simply do nothing.
+
 The native SDK registers its `ActivityLifecycleCallbacks` **inside**
 `initialize()`. In a React Native app that runs long after `MainActivity`'s
 `onActivityCreated` has already fired, so **the intent that cold-started your
@@ -181,7 +273,7 @@ app is never seen by those callbacks.**
 
 This wrapper works around it by forwarding `currentActivity.intent` at the end
 of `initialize()`. For links that arrive while the app is already running, call
-`handleNotificationIntent()` yourself:
+`handleIntent()` yourself:
 
 ```ts
 useEffect(() => {
@@ -189,13 +281,13 @@ useEffect(() => {
 
   // Deep link received while the app is running.
   const link = Linking.addEventListener('url', () => {
-    BooleanMaths.handleNotificationIntent();
+    BooleanMaths.handleIntent();
   });
 
   // Notification tap that brought the app back to the foreground.
   const state = AppState.addEventListener('change', (next) => {
     if (next === 'active') {
-      BooleanMaths.handleNotificationIntent();
+      BooleanMaths.handleIntent();
     }
   });
 
@@ -255,9 +347,11 @@ Watch it land with:
 adb logcat -s BooleanMathsSDK:D EventDispatcher:D
 ```
 
-A successful tap logs `Notification click tracked with campaign data.`,
-persists a `NotificationClick` event, and dispatches it with the campaign
-fields nested under `data.notification`.
+The demo's tap intent is an `ACTION_VIEW` deep link, so a successful tap logs
+`Deep link click tracked with campaign data.`, persists a `DeepLinkClick`
+event, and dispatches it with the campaign fields nested under `data.link`. An
+intent without `ACTION_VIEW` takes the `NotificationClick` path instead — see
+[Automatic events](#automatic-events).
 
 ---
 
@@ -265,41 +359,85 @@ fields nested under `data.notification`.
 
 The native SDK tracks these without any call from you:
 
-| Event | When |
-| :---- | :--- |
-| `app_opened` | First Activity creation / SDK initialization |
-| `FirstOpen` | Once per install, with Google Play Install Referrer attribution |
-| `NotificationClick` | Any intent with an action, data string, or extras is handled — see the caveat below |
+| Event | When | Android | iOS |
+| :---- | :--- | :-----: | :-: |
+| `app_opened` | First Activity creation / SDK initialization | ✅ | ✅ |
+| `FirstOpen` | Once per install | ✅ with Google Play Install Referrer attribution | ✅ but `data` is `{}` |
+| `DeepLinkClick` | An `ACTION_VIEW` intent is handled — ad deep links and app links. Campaign fields nest under `data.link` | ✅ | ❌ |
+| `NotificationClick` | Any other intent carrying campaign data is handled. Fields nest under `data.notification` | ✅ | ❌ |
 
-Visitor ID and session ID (30-minute timeout) are generated and persisted
-natively.
+On both platforms `FirstOpen` precedes `app_opened`, so a new install's stream
+reads in order. `FirstOpen` is PascalCase on the wire on purpose — the two
+platforms match byte-for-byte and backend install reporting keys off that exact
+string.
 
-> ⚠️ **`NotificationClick` fires on ordinary app opens too (native SDK v1.0.7).**
-> `extractCampaignData` records `intent.action` unconditionally, and
-> `handleNotificationIntent` emits the event whenever the resulting map is
-> non-empty. A launcher tap always carries `action = ACTION_MAIN`, so opening
-> the app normally produces:
->
-> ```json
-> { "event": "NotificationClick",
->   "data": { "notification": { "action": "android.intent.action.MAIN" } } }
-> ```
->
-> So `NotificationClick` counts **notification taps plus plain opens**, and
-> cannot be used as a tap metric without filtering. A real tap is
-> distinguishable downstream: it carries a `data` deep link and/or campaign
-> extras, whereas a launcher open has only `action`.
+Visitor ID and session ID (30-minute timeout) are generated and persisted
+natively on both platforms.
+
+**Attribution is Android-only.** Campaign data from a handled intent is
+persisted by `AttributionManager` and attached to **every subsequent event** as
+`data.attribution`. iOS produces no `data.attribution` block, since it handles
+no intents; Apple Search Ads attribution is deferred to a later release.
+
+### What counts as a campaign intent (native SDK v1.0.9)
+
+`handleIntent` ignores an intent when **all** of these hold, which is what a
+plain launcher tap looks like:
+
+- `action` is `ACTION_MAIN`, **and**
+- `categories` contains `CATEGORY_LAUNCHER`, **and**
+- there are no extras, **and**
+- `data` is `null`
+
+Anything else with non-empty campaign data is attributed: `ACTION_VIEW` emits
+`DeepLinkClick`, everything else emits `NotificationClick`. Intents are
+de-duplicated in a `WeakHashMap`, so re-forwarding the same intent is a no-op.
+
+> ℹ️ **This fixes a v1.0.7/v1.0.8 bug this README previously warned about.**
+> Older native SDKs recorded `intent.action` unconditionally and emitted
+> `NotificationClick` whenever the resulting map was non-empty — so an ordinary
+> launcher open produced a spurious
+> `{ "event": "NotificationClick", "data": { "notification": { "action": "android.intent.action.MAIN" } } }`
+> and the event could not be used as a tap metric without downstream
+> filtering. As of 1.0.9 the launcher case is skipped at the source, and real
+> deep links are split out into their own `DeepLinkClick` event.
 >
-> This wrapper reproduces the behaviour deliberately, for parity with native
-> Android and the Flutter wrapper — the native SDK does exactly the same via its
-> `onActivityCreated` callback. The fix belongs upstream in the Android SDK
-> (require deep-link data or extras before emitting the event), not here.
+> If you built dashboards or alerts that filter `NotificationClick` down to
+> real taps, revisit them: the noise is gone, and `ACTION_VIEW` taps now arrive
+> under a **different event name**.
 
 ---
 
 ## How properties cross the bridge
 
-Two normalizations happen on the Android side, both worth knowing:
+Each platform normalizes `properties` at the native boundary before handing it
+to the SDK. The rules differ because the two SDKs serialize differently — the
+observable payload is the same in the cases that matter.
+
+| Input | Android | iOS |
+| :---- | :------ | :-- |
+| `null` / `undefined` object value | Key dropped | Key dropped |
+| `null` inside an array | Preserved (indices must not shift) | Preserved |
+| Nested objects and arrays | Recursed | Recursed |
+| Whole numbers (`3`) | Coerced to integer — see the Gson caveat below | No action needed; `JSONSerialization` already emits `3`, not `3.0` |
+| Fractions (`999.5`) | Untouched | Untouched |
+| Booleans | Untouched | Untouched |
+| **`NaN` / `Infinity`** | Passed through as-is | **Key dropped** — see below |
+
+### iOS: why `NaN` is dropped rather than passed through
+
+This one is load-bearing, not cosmetic. The iOS SDK guards its writes with
+`JSONSerialization.isValidJSONObject(...)` and **silently discards the payload**
+when that returns false. A JS `NaN` or `Infinity` arrives as a non-finite
+`NSNumber` and invalidates the whole object — so a single bad property value
+could discard the event, or the entire outgoing batch. The wrapper strips those
+keys at the boundary so the rest of the event survives.
+
+`NSDate` and anything else not JSON-representable is dropped for the same
+reason. Everything is handled recursively, so a `NaN` nested three objects deep
+costs you that one key and nothing else.
+
+### Android normalization
 
 - **Integral numbers are converted to integers.** React Native passes every JS
   number across the bridge as a `Double`, so `{ count: 3 }` would otherwise be
@@ -311,7 +449,7 @@ Two normalizations happen on the Android side, both worth knowing:
   { "value": 2499, "items": [{ "quantity": 2, "price": 999.5 }] }
   ```
 
-  > ⚠️ **Known native SDK limitation (v1.0.7).** The integers do *not* survive
+  > ⚠️ **Known native SDK limitation (still present in v1.0.9).** The integers do *not* survive
   > to the wire. `EventDispatcher` re-reads the stored payload with
   > `gson.fromJson(properties, Map::class.java)`, and Gson coerces every number
   > in a raw `Map` to `Double` — so the request body ends up with `2499.0` and
@@ -325,28 +463,50 @@ Two normalizations happen on the Android side, both worth knowing:
   serializes with Gson, which omits null map values anyway, so the emitted JSON
   is identical. Nulls **inside arrays** are preserved so indices do not shift.
 
-Failures in the native bridge are logged (`adb logcat -s BooleanmathsRnSdk`)
-rather than thrown into JavaScript — analytics should never crash the host app.
+Failures in the native bridge are logged rather than thrown into JavaScript —
+analytics should never crash the host app. Android logs to
+`adb logcat -s BooleanmathsRnSdk`; iOS logs through `RCTLogError`, visible in
+Xcode's console and Metro.
 
 ---
 
 ## Troubleshooting
 
 **No events arriving.** Confirm `BooleanMaths.isSupported` is `true`, then check
-`adb logcat -s BooleanMathsSDK:D BooleanmathsRnSdk:D`. The native SDK logs each
-persisted event and the full payload it sends.
+the native logs — `adb logcat -s BooleanMathsSDK:D BooleanmathsRnSdk:D` on
+Android, or Xcode's console on iOS. The native SDK logs each persisted event and
+the full payload it sends.
 
 **Warning: "native module could not be found".** The JS installed but the native
-side did not. Rebuild the app (`npx react-native run-android`) rather than just
-reloading Metro; on iOS run `pod install`.
-
-**Events show a delay.** By design. Each `trackEvent` enqueues an immediate
-sync attempt, but WorkManager also runs a periodic 15-minute batch job and
-requires network connectivity.
-
-**Deep link not attributed.** See
-[Deep links](#deep-links-and-notification-attribution) — the launch intent needs
-explicit forwarding, and `singleTask` activities need `setIntent`.
+side did not. Rebuild the app (`npx react-native run-android`, or `pod install`
+followed by `npx react-native run-ios`) rather than just reloading Metro.
+
+**iOS: crash at launch with a dyld "Library not loaded" / "image not found"
+error naming `BooleanMathsSDK`.** The XCFramework is a *dynamic* framework and
+was not embedded. Confirm the `[CP] Embed Pods Frameworks` build phase exists on
+your app target, then `pod deintegrate && pod install`. This is the one iOS
+failure mode that builds cleanly and only shows up at runtime.
+
+**iOS: `getHelloMessage()` returns an empty string.** The bridge resolved but the
+native SDK call failed — check the Xcode console for a
+`BooleanMaths getHelloMessage failed` error. An empty string here specifically
+means the XCFramework did not link correctly.
+
+**iOS: `pod install` fails to resolve `BooleanMathsSDK`.** Run
+`pod repo update`, and confirm your app's deployment target is 15.1 or higher.
+If the lockfile pinned `1.0.0`, delete that entry and reinstall — 1.0.0 carries
+an iOS 17.0 floor.
+
+**Events show a delay.** By design on both platforms. Each `trackEvent`
+enqueues an immediate sync attempt; Android's WorkManager also runs a periodic
+15-minute batch job and requires network connectivity, and iOS flushes when the
+app backgrounds.
+
+**Deep link not attributed.** Android only — see
+[Deep links](#deep-links-and-notification-attribution); the launch intent needs
+explicit forwarding, and `singleTask` activities need `setIntent`. On iOS deep
+link attribution is not implemented at all
+([what iOS supports](#what-ios-supports)).
 
 ---
 
@@ -358,7 +518,7 @@ explicit forwarding, and `singleTask` activities need `setIntent`.
 
 ## License
 
-MIT
+[Apache-2.0](LICENSE)
 
 ---
 

package/android/build.gradle

@@ -6,7 +6,7 @@ buildscript {
     // Version of the native Android SDK (com.booleanmaths:bm-sdk) this wrapper
     // is built against. Override with `ext.BooleanmathsRnSdk_bmSdkVersion` in
     // your app's root build.gradle to pin a different one.
-    bmSdkVersion: "1.0.8"
+    bmSdkVersion: "1.0.9"
   ]
 
   ext.getExtOrDefault = { prop ->

package/android/src/main/java/com/booleanmathsrnsdk/BooleanmathsRnSdkModule.kt

@@ -41,6 +41,16 @@ class BooleanmathsRnSdkModule(reactContext: ReactApplicationContext) :
     }
   }
 
+  override fun handleIntent() {
+    safely("handleIntent") { forwardCurrentIntent() }
+  }
+
+  /**
+   * Alias of [handleIntent]. The native SDK unified ad deep links, app links
+   * and push notifications behind `handleIntent` in 1.0.9 and kept
+   * `handleNotificationIntent` as a delegating alias; this mirrors that so
+   * apps written against the older name keep working unchanged.
+   */
   override fun handleNotificationIntent() {
     safely("handleNotificationIntent") { forwardCurrentIntent() }
   }
@@ -64,7 +74,7 @@ class BooleanmathsRnSdkModule(reactContext: ReactApplicationContext) :
 
     // The native SDK de-duplicates intents it has already processed, so
     // calling this more than once for the same intent is safe.
-    BooleanMathsSDK.handleNotificationIntent(intent)
+    BooleanMathsSDK.handleIntent(intent)
   }
 
   /**

package/ios/BMBooleanMathsBridge.swift

@@ -0,0 +1,146 @@
+import Foundation
+import BooleanMathsSDK
+
+/// Objective-C-visible shim over the pure Swift `BooleanMathsSDK`.
+///
+/// This file is mandatory, not a stylistic layer. `BooleanMaths` is declared
+/// `@MainActor public final class` — it is not `@objc` and not `NSObject`-derived
+/// (and cannot trivially become `@objc`, which requires `NSObject` inheritance).
+/// The SDK's generated `BooleanMathsSDK-Swift.h` therefore contains zero
+/// `@interface` declarations, so `#import <BooleanMathsSDK/...>` from
+/// `BooleanmathsRnSdk.mm` resolves to an empty module and the TurboModule cannot
+/// see the SDK at all.
+///
+/// Everything here takes only Objective-C-representable types and is reached
+/// from the `.mm` through the pod's generated `BooleanmathsRnSdk-Swift.h`.
+///
+/// Behaviour is specified by the Android module
+/// (`android/src/main/java/com/booleanmathsrnsdk/BooleanmathsRnSdkModule.kt`),
+/// which is the reference implementation for this wrapper.
+@objc(BMBooleanMathsBridge)
+public final class BMBooleanMathsBridge: NSObject {
+
+  /// Matches Android's `BuildConfig.WRAPPER_TYPE`.
+  private static let wrapperType = "react-native"
+
+  // MARK: - Public API
+
+  /// Initializes the native SDK and stamps this wrapper's identity onto it.
+  ///
+  /// `@MainActor` because `BooleanMaths.initialize` is main-actor isolated. The
+  /// caller in `BooleanmathsRnSdk.mm` hops with `dispatch_async` before invoking
+  /// this — never `dispatch_sync`, which deadlocks when the JS thread is the
+  /// main thread.
+  ///
+  /// Named `initializeSdk` rather than `initialize` for the same reason the
+  /// codegen spec is: `+[NSObject initialize]` already exists.
+  @MainActor
+  @objc(initializeSdkWithApiKey:pixelId:wrapperVersion:)
+  public static func initializeSdk(
+    apiKey: String,
+    pixelId: String,
+    wrapperVersion: String
+  ) {
+    // Before `initialize`, not after: `initialize` itself emits `FirstOpen` and
+    // `app_opened` internally, and those must already carry wrapper_type /
+    // wrapper_version. Same ordering rationale as Android.
+    //
+    // Do NOT port Android's second, post-initialize call. Android needs it
+    // because its native SDK can only persist to SharedPreferences once it holds
+    // an application context, which it acquires inside initialize(). iOS has no
+    // such gap: `WrapperConfigStore.set` writes to UserDefaults unconditionally,
+    // and `initialize` calls `rehydrate()`, which fills each field only where it
+    // is still nil — so a value set earlier in the process outranks the
+    // persisted one. One call, before initialize, is correct and sufficient.
+    BooleanMaths.shared.setWrapperConfig(type: wrapperType, version: wrapperVersion)
+
+    BooleanMaths.shared.initialize(apiKey: apiKey, pixelId: pixelId)
+
+    // There is no iOS equivalent of Android's forwardCurrentIntent(): deep links
+    // are deferred on iOS, so nothing is forwarded here. See `handleIntent` in
+    // BooleanmathsRnSdk.mm.
+  }
+
+  /// Records a custom event. `properties` is sanitized first — see
+  /// `sanitized(value:allowNull:)` for why that is load-bearing.
+  ///
+  /// `@MainActor` because `BooleanMaths.track` is main-actor isolated.
+  @MainActor
+  @objc(trackEventWithName:properties:)
+  public static func trackEvent(name: String, properties: [String: Any]?) {
+    BooleanMaths.shared.track(name, properties: sanitized(dictionary: properties ?? [:]))
+  }
+
+  /// Bridge smoke test. Deliberately not main-actor isolated: the TurboModule
+  /// method is synchronous and returns the value directly, so it must not hop
+  /// threads. `BooleanMaths.getHelloMessage()` is `nonisolated static` in the SDK
+  /// specifically to allow this.
+  ///
+  /// A real SDK call rather than a wrapper-side literal, so it also proves the
+  /// XCFramework actually linked.
+  @objc(getHelloMessage)
+  public static func getHelloMessage() -> String {
+    BooleanMaths.getHelloMessage()
+  }
+
+  // MARK: - Properties sanitization
+
+  // `EventDispatcher` and `EventStore` both guard on
+  // `JSONSerialization.isValidJSONObject(...)` and silently drop the payload when
+  // it returns false. A JS `NaN` or `Infinity` arrives here as a non-finite
+  // NSNumber and makes the whole object invalid — so one bad property value can
+  // discard the event, or the entire outgoing batch. Android guards the same case
+  // in `normalizeValue`.
+
+  private static func sanitized(dictionary: [String: Any]) -> [String: Any] {
+    var result = [String: Any](minimumCapacity: dictionary.count)
+
+    for (key, value) in dictionary {
+      guard let clean = sanitized(value: value, allowNull: false) else { continue }
+      result[key] = clean
+    }
+
+    return result
+  }
+
+  /// Nulls are preserved inside arrays — dropping them would shift indices.
+  /// Android preserves them deliberately for the same reason.
+  private static func sanitized(array: [Any]) -> [Any] {
+    array.map { sanitized(value: $0, allowNull: true) ?? NSNull() }
+  }
+
+  private static func sanitized(value: Any, allowNull: Bool) -> Any? {
+    switch value {
+    case is NSNull:
+      // Dropped as an object value (matching Android, whose Gson omits null map
+      // values anyway), kept inside an array.
+      return allowNull ? NSNull() : nil
+
+    case let number as NSNumber:
+      // Must be tested before any `as Bool` cast: `NSNumber(1) as? Bool`
+      // succeeds under Swift bridging, so checking Bool first would silently
+      // turn `{ count: 1 }` into `{ count: true }`. Booleans arrive from React
+      // Native as CFBoolean, match here, and serialize as true/false unchanged.
+      //
+      // No whole-number coercion: Android's `toWholeNumberOrSelf` fixes a
+      // Gson-specific artifact, whereas JSONSerialization already emits `3`
+      // rather than `3.0`.
+      return number.doubleValue.isFinite ? number : nil
+
+    case let string as String:
+      return string
+
+    case let nested as [String: Any]:
+      return sanitized(dictionary: nested)
+
+    case let nested as [Any]:
+      return sanitized(array: nested)
+
+    default:
+      // NSDate and anything else not JSON-representable, plus dictionaries with
+      // non-String keys. React Native never produces these from a JS object, but
+      // passing one through would invalidate the payload.
+      return nil
+    }
+  }
+}

package/ios/BooleanmathsRnSdk.h

@@ -1,19 +1,20 @@
 #import <BooleanmathsRnSdkSpec/BooleanmathsRnSdkSpec.h>
 
 /**
- * iOS no-op implementation of the BooleanMaths SDK.
+ * iOS implementation of the BooleanMaths TurboModule, backed by the
+ * `BooleanMathsSDK` pod (>= 1.0.1, minimum iOS 15.1).
  *
- * There is no native BooleanMaths iOS SDK published yet (the native SDK ships
- * for Android only, as `com.booleanmaths:bm-sdk`). This class exists so that
- * the TurboModule still resolves on iOS and every call degrades into a
- * harmless no-op instead of crashing the host app.
+ * The SDK itself is pure Swift and exposes no Objective-C surface, so this class
+ * does not talk to it directly — every call goes through
+ * `BMBooleanMathsBridge` (`ios/BMBooleanMathsBridge.swift`), which explains why
+ * in detail.
  *
- * In practice these methods are never reached: the JavaScript layer gates on
- * `Platform.OS` and returns before touching the bridge. They are implemented
- * anyway as a backstop.
+ * `initializeSdk` and `trackEvent` hop to the main queue because the SDK is
+ * `@MainActor`; `getHelloMessage` deliberately does not, being synchronous and
+ * value-returning. Failures are logged and swallowed rather than thrown into JS.
  *
- * When an iOS SDK becomes available, replace the bodies below and flip
- * `SUPPORTED_PLATFORMS` in `src/BooleanMaths.native.tsx` to include 'ios'.
+ * `handleIntent` and `handleNotificationIntent` remain no-ops: intents are an
+ * Android concept and iOS deep links are out of scope for this release.
  */
 @interface BooleanmathsRnSdk : NSObject <NativeBooleanmathsRnSdkSpec>
 

package/ios/BooleanmathsRnSdk.mm

@@ -2,44 +2,104 @@
 
 #import <React/RCTLog.h>
 
+// The generated header for BMBooleanMathsBridge.swift. Both paths are needed so
+// this builds under static and dynamic pod linkage alike.
+#if __has_include(<BooleanmathsRnSdk/BooleanmathsRnSdk-Swift.h>)
+#import <BooleanmathsRnSdk/BooleanmathsRnSdk-Swift.h>
+#else
+#import "BooleanmathsRnSdk-Swift.h"
+#endif
+
+// Injected by BooleanmathsRnSdk.podspec from package.json's version, mirroring
+// Android's BuildConfig.WRAPPER_VERSION. Only reached if that xcconfig failed to
+// apply, in which case a wrong-looking wrapper_version is far better than a
+// build error in a consumer's app.
+#ifndef BMRN_WRAPPER_VERSION
+#define BMRN_WRAPPER_VERSION "unknown"
+#endif
+
 @implementation BooleanmathsRnSdk
 
 /**
- * Logs the "no iOS SDK" warning at most once per app launch so it is visible
- * without flooding the console if something does call through.
+ * Analytics must never take the host app down. Mirrors Android's `safely()`
+ * helper: log the failure and swallow it rather than surfacing it to JS.
+ */
+static void BMSafely(NSString *operation, void (^block)(void))
+{
+  @try {
+    block();
+  } @catch (NSException *exception) {
+    RCTLogError(@"[@booleanmaths/booleanmaths-rn-sdk] BooleanMaths %@ failed: %@", operation, exception);
+  }
+}
+
+/**
+ * Logs the "deep links are Android-only" notice at most once per app launch, so
+ * it is visible without flooding the console.
  */
-static void BMWarnUnsupportedOnce(void)
+static void BMWarnIntentUnsupportedOnce(void)
 {
   static dispatch_once_t onceToken;
   dispatch_once(&onceToken, ^{
-    RCTLogWarn(@"[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on iOS "
-               @"(Android only for now). All SDK calls are no-ops and no events will be "
-               @"tracked on this platform.");
+    RCTLogWarn(@"[@booleanmaths/booleanmaths-rn-sdk] Deep-link and notification intent forwarding is "
+               @"Android-only; handleIntent() is a no-op on iOS. Event tracking is fully supported — "
+               @"only intent attribution is unavailable.");
   });
 }
 
 - (void)initializeSdk:(NSString *)apiKey pixelId:(NSString *)pixelId
 {
-  BMWarnUnsupportedOnce();
+  // Captured outside the block: it is a compile-time constant, not thread state.
+  NSString *wrapperVersion = @BMRN_WRAPPER_VERSION;
+
+  // BooleanMaths is @MainActor. dispatch_async, never dispatch_sync — the latter
+  // deadlocks whenever the JS thread is the main thread.
+  dispatch_async(dispatch_get_main_queue(), ^{
+    BMSafely(@"initialize", ^{
+      [BMBooleanMathsBridge initializeSdkWithApiKey:apiKey
+                                            pixelId:pixelId
+                                     wrapperVersion:wrapperVersion];
+    });
+  });
 }
 
 - (void)trackEvent:(NSString *)name properties:(NSDictionary *)properties
 {
-  BMWarnUnsupportedOnce();
+  dispatch_async(dispatch_get_main_queue(), ^{
+    BMSafely(@"trackEvent", ^{
+      [BMBooleanMathsBridge trackEventWithName:name properties:properties];
+    });
+  });
+}
+
+- (void)handleIntent
+{
+  // Deliberately still a no-op. Intents are an Android concept, and iOS deep
+  // links / universal links are deferred — their absence here is scope, not a
+  // missing implementation.
+  BMWarnIntentUnsupportedOnce();
 }
 
 - (void)handleNotificationIntent
 {
-  // Android-only concept; nothing to do on iOS even once an iOS SDK exists.
-  BMWarnUnsupportedOnce();
+  // Alias of handleIntent, mirroring the Android bridge.
+  BMWarnIntentUnsupportedOnce();
 }
 
 - (NSString *)getHelloMessage
 {
-  BMWarnUnsupportedOnce();
+  // No dispatch: this is synchronous and returns a value, so it must not hop
+  // threads. The SDK's getHelloMessage() is `nonisolated static` to allow it.
+  @try {
+    return [BMBooleanMathsBridge getHelloMessage];
+  } @catch (NSException *exception) {
+    RCTLogError(@"[@booleanmaths/booleanmaths-rn-sdk] BooleanMaths getHelloMessage failed: %@", exception);
 
-  // Deliberately not nil: the codegen spec declares a non-optional string.
-  return @"BooleanMaths SDK is not available on iOS";
+    // Empty rather than a plausible-looking message: this method exists to prove
+    // the native SDK linked, so a failure must read as a failure. The codegen
+    // spec declares a non-optional string, so it cannot be nil.
+    return @"";
+  }
 }
 
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:

package/lib/module/BooleanMaths.js

@@ -23,6 +23,9 @@ export const BooleanMaths = {
   trackEvent(_name, _properties) {
     warnOnce();
   },
+  handleIntent() {
+    warnOnce();
+  },
   handleNotificationIntent() {
     warnOnce();
   },

package/lib/module/BooleanMaths.js.map

@@ -1 +1 @@
-{"version":3,"names":["hasWarned","warnOnce","__DEV__","console","warn","BooleanMaths","isSupported","initialize","_apiKey","_pixelId","trackEvent","_name","_properties","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.tsx"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAIA,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,OAAOE,OAAO,KAAK,WAAW,IAAI,CAACA,OAAO,EAAE;IAC3D;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhBG,OAAO,CAACC,IAAI,CACV,sFAAsF,GACpF,2EAA2E,GAC3E,8DACJ,CAAC;AACH;AAEA,OAAO,MAAMC,YAA6B,GAAG;EAC3CC,WAAW,EAAE,KAAK;EAElBC,UAAUA,CAACC,OAAe,EAAEC,QAAgB,EAAQ;IAClDR,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDS,UAAUA,CAACC,KAAa,EAAEC,WAAyC,EAAQ;IACzEX,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDY,wBAAwBA,CAAA,EAAS;IAC/BZ,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDa,eAAeA,CAAA,EAAkB;IAC/Bb,QAAQ,CAAC,CAAC;IACV,OAAO,IAAI;EACb;AACF,CAAC","ignoreList":[]}
+{"version":3,"names":["hasWarned","warnOnce","__DEV__","console","warn","BooleanMaths","isSupported","initialize","_apiKey","_pixelId","trackEvent","_name","_properties","handleIntent","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.tsx"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAIA,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,OAAOE,OAAO,KAAK,WAAW,IAAI,CAACA,OAAO,EAAE;IAC3D;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhBG,OAAO,CAACC,IAAI,CACV,sFAAsF,GACpF,2EAA2E,GAC3E,8DACJ,CAAC;AACH;AAEA,OAAO,MAAMC,YAA6B,GAAG;EAC3CC,WAAW,EAAE,KAAK;EAElBC,UAAUA,CAACC,OAAe,EAAEC,QAAgB,EAAQ;IAClDR,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDS,UAAUA,CAACC,KAAa,EAAEC,WAAyC,EAAQ;IACzEX,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDY,YAAYA,CAAA,EAAS;IACnBZ,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDa,wBAAwBA,CAAA,EAAS;IAC/Bb,QAAQ,CAAC,CAAC;EACZ,CAAC;EAEDc,eAAeA,CAAA,EAAkB;IAC/Bd,QAAQ,CAAC,CAAC;IACV,OAAO,IAAI;EACb;AACF,CAAC","ignoreList":[]}

package/lib/module/BooleanMaths.native.js

@@ -3,11 +3,15 @@
 import { Platform } from 'react-native';
 import NativeBooleanmathsRnSdk from "./NativeBooleanmathsRnSdk.js";
 /**
- * The BooleanMaths native SDK currently ships for Android only. There is no
- * iOS artifact yet, so on iOS every call below short-circuits and the SDK
- * behaves as a silent no-op rather than crashing the app.
+ * The BooleanMaths native SDK ships for Android (`com.booleanmaths:bm-sdk`) and
+ * iOS (`BooleanMathsSDK`). Any other platform — including out-of-tree React
+ * Native targets — has no native artifact, so every call below short-circuits
+ * and the SDK behaves as a silent no-op rather than crashing the app.
+ *
+ * Note that `handleIntent` is a no-op on iOS even though iOS is supported here:
+ * intents are an Android concept. See its JSDoc in `./types`.
  */
-const SUPPORTED_PLATFORMS = ['android'];
+const SUPPORTED_PLATFORMS = ['android', 'ios'];
 const isPlatformSupported = SUPPORTED_PLATFORMS.includes(Platform.OS);
 
 /**
@@ -23,11 +27,25 @@ function warnOnce() {
   }
   hasWarned = true;
   if (!isPlatformSupported) {
-    console.warn(`[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on ${Platform.OS} ` + '(Android only for now). All SDK calls are no-ops on this platform and no ' + 'events will be tracked. Gate your calls on `BooleanMaths.isSupported` to ' + 'silence this warning — see the README\'s "Platform support" section.');
+    console.warn(`[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on ${Platform.OS} ` + '(Android and iOS only). All SDK calls are no-ops on this platform and no ' + 'events will be tracked. Gate your calls on `BooleanMaths.isSupported` to ' + 'silence this warning — see the README\'s "Platform support" section.');
     return;
   }
   console.warn('[@booleanmaths/booleanmaths-rn-sdk] The native module could not be found on ' + `${Platform.OS}. Rebuild the app after installing the package (a Metro ` + 'reload is not enough), and on iOS run `pod install`. All SDK calls are ' + 'no-ops until this is fixed.');
 }
+
+/**
+ * Shared by `handleIntent` and its `handleNotificationIntent` alias. A
+ * standalone function rather than `this.handleIntent()` so the alias keeps
+ * working when it is pulled off the object, as in
+ * `const { handleNotificationIntent } = BooleanMaths`.
+ */
+function forwardCurrentIntent() {
+  if (!isSupported) {
+    warnOnce();
+    return;
+  }
+  NativeBooleanmathsRnSdk.handleIntent();
+}
 export const BooleanMaths = {
   isSupported,
   initialize(apiKey, pixelId) {
@@ -44,13 +62,8 @@ export const BooleanMaths = {
     }
     NativeBooleanmathsRnSdk.trackEvent(name, properties);
   },
-  handleNotificationIntent() {
-    if (!isSupported) {
-      warnOnce();
-      return;
-    }
-    NativeBooleanmathsRnSdk.handleNotificationIntent();
-  },
+  handleIntent: forwardCurrentIntent,
+  handleNotificationIntent: forwardCurrentIntent,
   getHelloMessage() {
     if (!isSupported) {
       warnOnce();

package/lib/module/BooleanMaths.native.js.map

@@ -1 +1 @@
-{"version":3,"names":["Platform","NativeBooleanmathsRnSdk","SUPPORTED_PLATFORMS","isPlatformSupported","includes","OS","isSupported","hasWarned","warnOnce","__DEV__","console","warn","BooleanMaths","initialize","apiKey","pixelId","initializeSdk","trackEvent","name","properties","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.native.tsx"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,cAAc;AACvC,OAAOC,uBAAuB,MAAM,8BAA2B;AAG/D;AACA;AACA;AACA;AACA;AACA,MAAMC,mBAAsD,GAAG,CAAC,SAAS,CAAC;AAE1E,MAAMC,mBAAmB,GAAGD,mBAAmB,CAACE,QAAQ,CAACJ,QAAQ,CAACK,EAAE,CAAC;;AAErE;AACA;AACA;AACA;AACA;AACA,MAAMC,WAAW,GAAGH,mBAAmB,IAAIF,uBAAuB,IAAI,IAAI;AAE1E,IAAIM,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,CAACE,OAAO,EAAE;IACzB;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhB,IAAI,CAACJ,mBAAmB,EAAE;IACxBO,OAAO,CAACC,IAAI,CACV,uFAAuFX,QAAQ,CAACK,EAAE,GAAG,GACnG,2EAA2E,GAC3E,2EAA2E,GAC3E,sEACJ,CAAC;IACD;EACF;EAEAK,OAAO,CAACC,IAAI,CACV,8EAA8E,GAC5E,GAAGX,QAAQ,CAACK,EAAE,0DAA0D,GACxE,yEAAyE,GACzE,6BACJ,CAAC;AACH;AAEA,OAAO,MAAMO,YAA6B,GAAG;EAC3CN,WAAW;EAEXO,UAAUA,CAACC,MAAc,EAAEC,OAAe,EAAQ;IAChD,IAAI,CAACT,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEe,aAAa,CAACF,MAAM,EAAEC,OAAO,CAAC;EACzD,CAAC;EAEDE,UAAUA,CAACC,IAAY,EAAEC,UAAuC,GAAG,CAAC,CAAC,EAAQ;IAC3E,IAAI,CAACb,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEgB,UAAU,CAACC,IAAI,EAAEC,UAAU,CAAC;EACvD,CAAC;EAEDC,wBAAwBA,CAAA,EAAS;IAC/B,IAAI,CAACd,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEmB,wBAAwB,CAAC,CAAC;EACrD,CAAC;EAEDC,eAAeA,CAAA,EAAkB;IAC/B,IAAI,CAACf,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV,OAAO,IAAI;IACb;IAEA,OAAOP,uBAAuB,CAAEoB,eAAe,CAAC,CAAC;EACnD;AACF,CAAC","ignoreList":[]}
+{"version":3,"names":["Platform","NativeBooleanmathsRnSdk","SUPPORTED_PLATFORMS","isPlatformSupported","includes","OS","isSupported","hasWarned","warnOnce","__DEV__","console","warn","forwardCurrentIntent","handleIntent","BooleanMaths","initialize","apiKey","pixelId","initializeSdk","trackEvent","name","properties","handleNotificationIntent","getHelloMessage"],"sourceRoot":"../../src","sources":["BooleanMaths.native.tsx"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,cAAc;AACvC,OAAOC,uBAAuB,MAAM,8BAA2B;AAG/D;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,mBAAsD,GAAG,CAC7D,SAAS,EACT,KAAK,CACN;AAED,MAAMC,mBAAmB,GAAGD,mBAAmB,CAACE,QAAQ,CAACJ,QAAQ,CAACK,EAAE,CAAC;;AAErE;AACA;AACA;AACA;AACA;AACA,MAAMC,WAAW,GAAGH,mBAAmB,IAAIF,uBAAuB,IAAI,IAAI;AAE1E,IAAIM,SAAS,GAAG,KAAK;AAErB,SAASC,QAAQA,CAAA,EAAG;EAClB,IAAID,SAAS,IAAI,CAACE,OAAO,EAAE;IACzB;EACF;EAEAF,SAAS,GAAG,IAAI;EAEhB,IAAI,CAACJ,mBAAmB,EAAE;IACxBO,OAAO,CAACC,IAAI,CACV,uFAAuFX,QAAQ,CAACK,EAAE,GAAG,GACnG,2EAA2E,GAC3E,2EAA2E,GAC3E,sEACJ,CAAC;IACD;EACF;EAEAK,OAAO,CAACC,IAAI,CACV,8EAA8E,GAC5E,GAAGX,QAAQ,CAACK,EAAE,0DAA0D,GACxE,yEAAyE,GACzE,6BACJ,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,SAASO,oBAAoBA,CAAA,EAAS;EACpC,IAAI,CAACN,WAAW,EAAE;IAChBE,QAAQ,CAAC,CAAC;IACV;EACF;EAEAP,uBAAuB,CAAEY,YAAY,CAAC,CAAC;AACzC;AAEA,OAAO,MAAMC,YAA6B,GAAG;EAC3CR,WAAW;EAEXS,UAAUA,CAACC,MAAc,EAAEC,OAAe,EAAQ;IAChD,IAAI,CAACX,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEiB,aAAa,CAACF,MAAM,EAAEC,OAAO,CAAC;EACzD,CAAC;EAEDE,UAAUA,CAACC,IAAY,EAAEC,UAAuC,GAAG,CAAC,CAAC,EAAQ;IAC3E,IAAI,CAACf,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV;IACF;IAEAP,uBAAuB,CAAEkB,UAAU,CAACC,IAAI,EAAEC,UAAU,CAAC;EACvD,CAAC;EAEDR,YAAY,EAAED,oBAAoB;EAElCU,wBAAwB,EAAEV,oBAAoB;EAE9CW,eAAeA,CAAA,EAAkB;IAC/B,IAAI,CAACjB,WAAW,EAAE;MAChBE,QAAQ,CAAC,CAAC;MACV,OAAO,IAAI;IACb;IAEA,OAAOP,uBAAuB,CAAEsB,eAAe,CAAC,CAAC;EACnD;AACF,CAAC","ignoreList":[]}

package/lib/module/NativeBooleanmathsRnSdk.js.map

@@ -1 +1 @@
-{"version":3,"names":["TurboModuleRegistry","get"],"sourceRoot":"../../src","sources":["NativeBooleanmathsRnSdk.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;AAiBpE;AACA;AACA;AACA;AACA,eAAeA,mBAAmB,CAACC,GAAG,CAAO,mBAAmB,CAAC","ignoreList":[]}
+{"version":3,"names":["TurboModuleRegistry","get"],"sourceRoot":"../../src","sources":["NativeBooleanmathsRnSdk.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA0B,cAAc;AAsBpE;AACA;AACA;AACA;AACA,eAAeA,mBAAmB,CAACC,GAAG,CAAO,mBAAmB,CAAC","ignoreList":[]}

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

@@ -1 +1 @@
-{"version":3,"file":"BooleanMaths.d.ts","sourceRoot":"","sources":["../../../src/BooleanMaths.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA+B,MAAM,YAAS,CAAC;AAyB5E,eAAO,MAAM,YAAY,EAAE,eAmB1B,CAAC"}
+{"version":3,"file":"BooleanMaths.d.ts","sourceRoot":"","sources":["../../../src/BooleanMaths.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA+B,MAAM,YAAS,CAAC;AAyB5E,eAAO,MAAM,YAAY,EAAE,eAuB1B,CAAC"}

package/lib/typescript/src/BooleanMaths.native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BooleanMaths.native.d.ts","sourceRoot":"","sources":["../../../src/BooleanMaths.native.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAA+B,MAAM,YAAS,CAAC;AA6C5E,eAAO,MAAM,YAAY,EAAE,eAsC1B,CAAC"}
+{"version":3,"file":"BooleanMaths.native.d.ts","sourceRoot":"","sources":["../../../src/BooleanMaths.native.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAA+B,MAAM,YAAS,CAAC;AAmE5E,eAAO,MAAM,YAAY,EAAE,eAiC1B,CAAC"}

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

@@ -9,6 +9,11 @@ export interface Spec extends TurboModule {
     initializeSdk(apiKey: string, pixelId: string): void;
     trackEvent(name: string, properties: Object): void;
     /** Android only. No-op elsewhere. */
+    handleIntent(): void;
+    /**
+     * Alias of `handleIntent`, kept so existing callers keep working. Android
+     * only. No-op elsewhere.
+     */
     handleNotificationIntent(): void;
     /** Smoke test that the native bridge is wired up. */
     getHelloMessage(): string;

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

@@ -1 +1 @@
-{"version":3,"file":"NativeBooleanmathsRnSdk.d.ts","sourceRoot":"","sources":["../../../src/NativeBooleanmathsRnSdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,qCAAqC;IACrC,wBAAwB,IAAI,IAAI,CAAC;IACjC,qDAAqD;IACrD,eAAe,IAAI,MAAM,CAAC;CAC3B;AAED;;;GAGG;;AACH,wBAAkE"}
+{"version":3,"file":"NativeBooleanmathsRnSdk.d.ts","sourceRoot":"","sources":["../../../src/NativeBooleanmathsRnSdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE,MAAM,WAAW,IAAK,SAAQ,WAAW;IACvC;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,qCAAqC;IACrC,YAAY,IAAI,IAAI,CAAC;IACrB;;;OAGG;IACH,wBAAwB,IAAI,IAAI,CAAC;IACjC,qDAAqD;IACrD,eAAe,IAAI,MAAM,CAAC;CAC3B;AAED;;;GAGG;;AACH,wBAAkE"}

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

@@ -25,22 +25,43 @@ export interface BooleanMathsApi {
      */
     trackEvent(name: string, properties?: BooleanMathsEventProperties): void;
     /**
-     * Forwards the current Activity's intent to the native SDK so deep-link and
-     * notification campaign data is attributed.
+     * Forwards the current Activity's intent to the native SDK so ad deep links,
+     * app links and push-notification campaign data are attributed.
      *
-     * Android only — a no-op on every other platform. Call this from your
-     * deep-link handler and once after `initialize`; see the README for why the
-     * launch intent needs this.
+     * This is the primary entry point for every kind of launch intent. Call it
+     * from your deep-link handler; `initialize` already forwards the launch
+     * intent itself (see the README for why that needs special handling).
+     *
+     * **Android only.** A no-op on iOS — not because iOS is unsupported (event
+     * tracking works fully there), but because intents are an Android concept and
+     * iOS deep links / universal links are out of scope for now. Safe to call
+     * unconditionally from shared code; on iOS it logs one dev-mode notice.
+     *
+     * Safe to call repeatedly — the native SDK de-duplicates intents it has
+     * already processed.
+     */
+    handleIntent(): void;
+    /**
+     * Backward-compatible alias of {@link handleIntent}.
+     *
+     * @deprecated Prefer `handleIntent()`, which names what it actually does:
+     * the native SDK routes deep links, app links and notifications through the
+     * same path. This alias will be kept for the foreseeable future.
      */
     handleNotificationIntent(): void;
     /**
      * Returns the native SDK's hello message, or `null` when there is no native
-     * SDK on this platform. Useful as a bridge smoke test.
+     * SDK on this platform.
+     *
+     * Useful as a bridge smoke test: the string comes from the native SDK itself
+     * on both Android and iOS, so a correct value also proves the native artifact
+     * actually linked.
      */
     getHelloMessage(): string | null;
     /**
-     * `true` only on platforms where a real BooleanMaths native SDK is linked.
-     * Currently Android only.
+     * `true` only on platforms where a real BooleanMaths native SDK is linked —
+     * Android and iOS. `false` on web, and on any platform where the native
+     * module failed to resolve (typically a JS install without a native rebuild).
      */
     readonly isSupported: boolean;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,yBAAyB,EAAE,GAC3B;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAAA;CAAE,CAAC;AAEjD,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACN,yBAAyB,CAC1B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAEzE;;;;;;;OAOG;IACH,wBAAwB,IAAI,IAAI,CAAC;IAEjC;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GACjC,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,yBAAyB,EAAE,GAC3B;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAAA;CAAE,CAAC;AAEjD,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACN,yBAAyB,CAC1B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;;;;;OAeG;IACH,YAAY,IAAI,IAAI,CAAC;IAErB;;;;;;OAMG;IACH,wBAAwB,IAAI,IAAI,CAAC;IAEjC;;;;;;;OAOG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booleanmaths/booleanmaths-rn-sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "React Native SDK for BooleanMaths — track user events and attribution in mobile apps.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/BooleanMaths.native.tsx

@@ -3,11 +3,18 @@ import NativeBooleanmathsRnSdk from './NativeBooleanmathsRnSdk';
 import type { BooleanMathsApi, BooleanMathsEventProperties } from './types';
 
 /**
- * The BooleanMaths native SDK currently ships for Android only. There is no
- * iOS artifact yet, so on iOS every call below short-circuits and the SDK
- * behaves as a silent no-op rather than crashing the app.
+ * The BooleanMaths native SDK ships for Android (`com.booleanmaths:bm-sdk`) and
+ * iOS (`BooleanMathsSDK`). Any other platform — including out-of-tree React
+ * Native targets — has no native artifact, so every call below short-circuits
+ * and the SDK behaves as a silent no-op rather than crashing the app.
+ *
+ * Note that `handleIntent` is a no-op on iOS even though iOS is supported here:
+ * intents are an Android concept. See its JSDoc in `./types`.
  */
-const SUPPORTED_PLATFORMS: ReadonlyArray<typeof Platform.OS> = ['android'];
+const SUPPORTED_PLATFORMS: ReadonlyArray<typeof Platform.OS> = [
+  'android',
+  'ios',
+];
 
 const isPlatformSupported = SUPPORTED_PLATFORMS.includes(Platform.OS);
 
@@ -30,7 +37,7 @@ function warnOnce() {
   if (!isPlatformSupported) {
     console.warn(
       `[@booleanmaths/booleanmaths-rn-sdk] The BooleanMaths native SDK is not available on ${Platform.OS} ` +
-        '(Android only for now). All SDK calls are no-ops on this platform and no ' +
+        '(Android and iOS only). All SDK calls are no-ops on this platform and no ' +
         'events will be tracked. Gate your calls on `BooleanMaths.isSupported` to ' +
         'silence this warning — see the README\'s "Platform support" section.'
     );
@@ -45,6 +52,21 @@ function warnOnce() {
   );
 }
 
+/**
+ * Shared by `handleIntent` and its `handleNotificationIntent` alias. A
+ * standalone function rather than `this.handleIntent()` so the alias keeps
+ * working when it is pulled off the object, as in
+ * `const { handleNotificationIntent } = BooleanMaths`.
+ */
+function forwardCurrentIntent(): void {
+  if (!isSupported) {
+    warnOnce();
+    return;
+  }
+
+  NativeBooleanmathsRnSdk!.handleIntent();
+}
+
 export const BooleanMaths: BooleanMathsApi = {
   isSupported,
 
@@ -66,14 +88,9 @@ export const BooleanMaths: BooleanMathsApi = {
     NativeBooleanmathsRnSdk!.trackEvent(name, properties);
   },
 
-  handleNotificationIntent(): void {
-    if (!isSupported) {
-      warnOnce();
-      return;
-    }
+  handleIntent: forwardCurrentIntent,
 
-    NativeBooleanmathsRnSdk!.handleNotificationIntent();
-  },
+  handleNotificationIntent: forwardCurrentIntent,
 
   getHelloMessage(): string | null {
     if (!isSupported) {

package/src/BooleanMaths.tsx

@@ -34,6 +34,10 @@ export const BooleanMaths: BooleanMathsApi = {
     warnOnce();
   },
 
+  handleIntent(): void {
+    warnOnce();
+  },
+
   handleNotificationIntent(): void {
     warnOnce();
   },

package/src/NativeBooleanmathsRnSdk.ts

@@ -10,6 +10,11 @@ export interface Spec extends TurboModule {
   initializeSdk(apiKey: string, pixelId: string): void;
   trackEvent(name: string, properties: Object): void;
   /** Android only. No-op elsewhere. */
+  handleIntent(): void;
+  /**
+   * Alias of `handleIntent`, kept so existing callers keep working. Android
+   * only. No-op elsewhere.
+   */
   handleNotificationIntent(): void;
   /** Smoke test that the native bridge is wired up. */
   getHelloMessage(): string;

package/src/types.ts

@@ -37,24 +37,46 @@ export interface BooleanMathsApi {
   trackEvent(name: string, properties?: BooleanMathsEventProperties): void;
 
   /**
-   * Forwards the current Activity's intent to the native SDK so deep-link and
-   * notification campaign data is attributed.
+   * Forwards the current Activity's intent to the native SDK so ad deep links,
+   * app links and push-notification campaign data are attributed.
    *
-   * Android only — a no-op on every other platform. Call this from your
-   * deep-link handler and once after `initialize`; see the README for why the
-   * launch intent needs this.
+   * This is the primary entry point for every kind of launch intent. Call it
+   * from your deep-link handler; `initialize` already forwards the launch
+   * intent itself (see the README for why that needs special handling).
+   *
+   * **Android only.** A no-op on iOS — not because iOS is unsupported (event
+   * tracking works fully there), but because intents are an Android concept and
+   * iOS deep links / universal links are out of scope for now. Safe to call
+   * unconditionally from shared code; on iOS it logs one dev-mode notice.
+   *
+   * Safe to call repeatedly — the native SDK de-duplicates intents it has
+   * already processed.
+   */
+  handleIntent(): void;
+
+  /**
+   * Backward-compatible alias of {@link handleIntent}.
+   *
+   * @deprecated Prefer `handleIntent()`, which names what it actually does:
+   * the native SDK routes deep links, app links and notifications through the
+   * same path. This alias will be kept for the foreseeable future.
    */
   handleNotificationIntent(): void;
 
   /**
    * Returns the native SDK's hello message, or `null` when there is no native
-   * SDK on this platform. Useful as a bridge smoke test.
+   * SDK on this platform.
+   *
+   * Useful as a bridge smoke test: the string comes from the native SDK itself
+   * on both Android and iOS, so a correct value also proves the native artifact
+   * actually linked.
    */
   getHelloMessage(): string | null;
 
   /**
-   * `true` only on platforms where a real BooleanMaths native SDK is linked.
-   * Currently Android only.
+   * `true` only on platforms where a real BooleanMaths native SDK is linked —
+   * Android and iOS. `false` on web, and on any platform where the native
+   * module failed to resolve (typically a JS install without a native rebuild).
    */
   readonly isSupported: boolean;
 }