@apex-inc/capacitor-plugin 0.3.8 → 2.1.0

package/ios/Sources/ApexCapacitorPlugin/ApexEvents.swift

@@ -0,0 +1,124 @@
+/**
+ * Apex Spec — canonical event name constants for the iOS SDK.
+ *
+ * Hand-authored from `app/src/lib/core/apex-spec/events.ts`. Kept in sync
+ * via the parity test at
+ * `app/src/lib/core/apex-spec/__tests__/sdk-parity.test.ts` — CI fails if a
+ * canonical name is added/renamed/removed in the registry without a matching
+ * update here.
+ *
+ * Usage from Swift:
+ *
+ *   plugin.track(type: ApexEvents.addToCart, data: ["product_id": "sku_123"])
+ *
+ * Each constant is the unversioned canonical name as the developer writes it
+ * in `track()` calls. Versions are an internal storage primitive; the SDK
+ * never carries a version field.
+ */
+
+import Foundation
+
+public enum ApexEvents {
+    // MARK: Commerce
+    public static let addToCart = "add_to_cart"
+    public static let removeFromCart = "remove_from_cart"
+    public static let productView = "product_view"
+    public static let addToWishlist = "add_to_wishlist"
+    public static let checkoutStarted = "checkout_started"
+    public static let inAppPurchase = "in_app_purchase"
+    public static let purchaseRefunded = "purchase_refunded"
+    public static let subscriptionEvent = "subscription_event"
+    public static let orderPlaced = "order_placed"
+    public static let firstSaleCompleted = "first_sale_completed"
+
+    // MARK: Marketing (merchant-fired triggers)
+    public static let priceDropped = "price_dropped"
+    public static let restockDue = "restock_due"
+    public static let reviewRequestDue = "review_request_due"
+
+    // MARK: Identity
+    public static let userSignedUp = "user_signed_up"
+    public static let userSignedIn = "user_signed_in"
+    public static let userSignedOut = "user_signed_out"
+    public static let userIdentified = "user_identified"
+
+    // MARK: Lifecycle
+    public static let appInstall = "app_install"
+    public static let appOpen = "app_open"
+    public static let appBackground = "app_background"
+    public static let appUninstall = "app_uninstall"
+    public static let appReinstall = "app_reinstall"
+
+    // MARK: Session
+    public static let sessionStart = "session_start"
+    public static let sessionEnd = "session_end"
+
+    // MARK: Engagement
+    public static let pageView = "page_view"
+    public static let pageview = "pageview"
+    public static let screenView = "screen_view"
+    public static let search = "search"
+    public static let share = "share"
+    public static let contentView = "content_view"
+    public static let formSubmit = "form_submit"
+    public static let click = "click"
+    public static let engagement = "engagement"
+    public static let heartbeat = "heartbeat"
+    public static let rageClick = "rage_click"
+    public static let deadClick = "dead_click"
+    public static let goalConversion = "goal_conversion"
+    public static let onboardingStepCompleted = "onboarding_step_completed"
+
+    // MARK: Product (PLG lifecycle outcomes)
+    public static let onboardingCompleted = "onboarding_completed"
+    public static let activated = "activated"
+
+    // MARK: Communication
+    public static let pushReceived = "push_received"
+    public static let pushOpened = "push_opened"
+    public static let emailOpened = "email_opened"
+    public static let emailClicked = "email_clicked"
+    public static let inAppMessageSeen = "in_app_message_seen"
+    public static let inAppMessageClicked = "in_app_message_clicked"
+
+    // MARK: Deep link
+    public static let deepLinkOpen = "deep_link_open"
+
+    // MARK: Attribution
+    public static let reattribution = "reattribution"
+    public static let reengagement = "reengagement"
+
+    // MARK: Smart banner
+    public static let smartBannerImpression = "smart_banner_impression"
+    public static let smartBannerClick = "smart_banner_click"
+    public static let smartBannerDismiss = "smart_banner_dismiss"
+
+    // MARK: System
+    public static let custom = "custom"
+    public static let lifecycleTransition = "lifecycle_transition"
+    public static let jsError = "js_error"
+
+    /// Apex Spec semver this SDK implements. Bumped together with
+    /// `APEX_SPEC_VERSION` in the TypeScript registry.
+    public static let specVersion = "1.1.0"
+
+    /// Complete list of every canonical event name. Used internally for
+    /// validation; iterate this set if you need to enumerate the spec.
+    public static let all: [String] = [
+        addToCart, removeFromCart, productView, addToWishlist, checkoutStarted,
+        inAppPurchase, purchaseRefunded, subscriptionEvent,
+        userSignedUp, userSignedIn, userSignedOut, userIdentified,
+        appInstall, appOpen, appBackground, appUninstall, appReinstall,
+        sessionStart, sessionEnd,
+        pageView, pageview, screenView, search, share, contentView, formSubmit,
+        click, engagement, heartbeat, rageClick, deadClick, goalConversion,
+        onboardingStepCompleted,
+        onboardingCompleted, activated,
+        pushReceived, pushOpened, emailOpened, emailClicked,
+        inAppMessageSeen, inAppMessageClicked,
+        deepLinkOpen,
+        reattribution, reengagement,
+        smartBannerImpression, smartBannerClick, smartBannerDismiss,
+        custom, lifecycleTransition, jsError,
+    ]
+}

package/ios/Sources/ApexCapacitorPlugin/BatchSender.swift

@@ -32,6 +32,9 @@ public final class NativeBatchSender {
     private let apiBaseUrl: String
     private let projectKey: String
     private let platformHeader: String
+    // Phase 2-SDK — optional workspace-bound API key forwarded as
+    // `x-apex-api-key` on every batch.
+    private let apiKey: String?
     private let batchSize: Int
     private let maxRetries: Int
     private let baseBackoffMs: Int
@@ -45,6 +48,7 @@ public final class NativeBatchSender {
         apiBaseUrl: String,
         projectKey: String,
         platformHeader: String = "ios",
+        apiKey: String? = nil,
         batchSize: Int = 50,
         maxRetries: Int = 3,
         baseBackoffMs: Int = 1000,
@@ -57,6 +61,7 @@ public final class NativeBatchSender {
         self.apiBaseUrl = trimmed
         self.projectKey = projectKey
         self.platformHeader = platformHeader
+        self.apiKey = apiKey
         self.batchSize = max(1, batchSize)
         self.maxRetries = max(1, maxRetries)
         self.baseBackoffMs = max(0, baseBackoffMs)
@@ -153,11 +158,21 @@ public final class NativeBatchSender {
         // We unwrap the queued envelope so the `id` lives at the top
         // level of each event object (matches what /api/events expects
         // and what the JS-side BatchSender produces).
+        //
+        // MMP-081 — stamp `clientType` at send time so events from the
+        // native iOS plugin land server-side as `native-ios`. We don't
+        // overwrite a value the caller already set on the event
+        // (preserves test fixtures and unusual workflows); the typical
+        // path is that the queued payload doesn't carry one and we
+        // fill it in here.
         let body: [String: Any] = [
             "projectKey": projectKey,
             "events": batch.map { ev -> [String: Any] in
                 var flat = ev.payload.mapValues { $0.value }
                 flat["id"] = ev.id
+                if flat["clientType"] == nil {
+                    flat["clientType"] = "native-ios"
+                }
                 return flat
             },
         ]
@@ -167,6 +182,9 @@ public final class NativeBatchSender {
         request.setValue("application/json", forHTTPHeaderField: "Content-Type")
         request.setValue(projectKey, forHTTPHeaderField: "X-Apex-Project-Key")
         request.setValue(platformHeader, forHTTPHeaderField: "X-Apex-Platform")
+        if let key = apiKey {
+            request.setValue(key, forHTTPHeaderField: "x-apex-api-key")
+        }
         request.timeoutInterval = 20
 
         do {

package/ios/Sources/ApexCapacitorPlugin/OfflineQueue.swift

@@ -165,6 +165,25 @@ public struct AnyCodable: Codable, Equatable {
         switch value {
         case is NSNull:
             try container.encodeNil()
+        case let n as NSNumber:
+            // 2026-05-16 — NSNumber discrimination. Capacitor's JS bridge
+            // hands us every JS number as NSNumber, and Objective-C's
+            // toll-free bridging means `NSNumber(value: 1)` and
+            // `NSNumber(value: true)` both satisfy `as Bool` AND `as Int`.
+            // The previous `case let v as Bool:` branch consumed integer
+            // 1 / 0 first, encoding `quantity: 1` from JS as `quantity:
+            // true` server-side. That broke a) commerce widgets reading
+            // quantity as a number, and b) any journey trigger that
+            // type-checks numeric fields. CFBooleanGetTypeID is the only
+            // reliable way to distinguish a true Bool NSNumber from an
+            // integer NSNumber on Apple platforms.
+            if CFGetTypeID(n) == CFBooleanGetTypeID() {
+                try container.encode(n.boolValue)
+            } else if CFNumberIsFloatType(n) {
+                try container.encode(n.doubleValue)
+            } else {
+                try container.encode(n.int64Value)
+            }
         case let v as Bool:
             try container.encode(v)
         case let v as Int:

package/ios/Sources/ApexCapacitorPlugin/PushNotificationManager.swift

@@ -60,6 +60,18 @@ public final class PushNotificationManager: NSObject {
     private let notificationCenter: NotificationCenter
     private var pendingCompletion: Completion?
 
+    /// Fired on EVERY token arrival, regardless of whether the
+    /// registration was kicked off by an explicit
+    /// `requestAuthorizationAndRegister` call or by `silentRegisterIfAuthorized`.
+    ///
+    /// The plugin uses this to forward the token to JS listeners and to
+    /// re-register the token with the Apex backend. Setting this from
+    /// `initialize` lets us silently refresh the token on every cold
+    /// start when permission is already granted — without this hook the
+    /// merchant would have to manually tap "Enable push" after every
+    /// fresh Xcode install just to surface the token in the dashboard.
+    public var onTokenReceived: ((String) -> Void)?
+
     public init(
         center: UNUserNotificationCenter = .current(),
         application: UIApplication = .shared,
@@ -113,6 +125,36 @@ public final class PushNotificationManager: NSObject {
         }
     }
 
+    /// Re-register for remote notifications WITHOUT prompting when
+    /// permission has already been granted. iOS's permission survives
+    /// app reinstalls (including Xcode debug rebuilds) but the sample
+    /// app's in-memory "have we registered yet?" state does not — so
+    /// merchants kept telling us push permission was "resetting on every
+    /// build". The OS hadn't actually reset anything; we just weren't
+    /// surfacing the fact that permission was still granted.
+    ///
+    /// Calling this on `initialize` re-fires `didRegisterForRemoteNotifications`
+    /// with the device's current token, which flows through `onTokenReceived`
+    /// and refreshes the dashboard registration with the latest plugin
+    /// metadata (including the APNs environment field that older builds
+    /// didn't report).
+    ///
+    /// No-op when permission is denied or hasn't been requested yet —
+    /// the user has to take an explicit action in those cases.
+    public func silentRegisterIfAuthorized() {
+        center.getNotificationSettings { [weak self] settings in
+            guard let self = self else { return }
+            switch settings.authorizationStatus {
+            case .authorized, .provisional, .ephemeral:
+                DispatchQueue.main.async {
+                    self.application.registerForRemoteNotifications()
+                }
+            default:
+                break
+            }
+        }
+    }
+
     // MARK: - AppDelegate bridge
 
     private func observeAppDelegateBridge() {
@@ -137,6 +179,11 @@ public final class PushNotificationManager: NSObject {
         }
         let hex = PushTokenHexFormatter.format(data)
         resolvePending(.init(permission: .granted, token: hex))
+        // Fire after resolvePending so the JS Promise for an explicit
+        // `Apex.registerForPushNotifications()` resolves first, then
+        // the plugin's persistent `onTokenReceived` hook runs to forward
+        // to listeners + the Apex backend.
+        onTokenReceived?(hex)
     }
 
     @objc private func handleDidFail(_: Notification) {

package/ios/Sources/ApexCapacitorPluginBridge/ApexCapacitorPlugin.swift

@@ -14,6 +14,9 @@ import Foundation
 import Capacitor
 import UIKit
 import UserNotifications
+#if canImport(StoreKit)
+import StoreKit
+#endif
 
 @objc(ApexCapacitorPlugin)
 public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificationCenterDelegate {
@@ -30,6 +33,7 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         CAPPluginMethod(name: "getInstallReferrer", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getVisitorId", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "setVisitorId", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "identify", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "updateConversionValue", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getInitialDeepLink", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getDeviceInfo", returnType: CAPPluginReturnPromise),
@@ -70,12 +74,25 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
     private var debug = false
     private var apiBaseUrl: String = ""
     private var projectKey: String = ""
+    // Phase 2-SDK — optional workspace-bound API key forwarded as
+    // `x-apex-api-key` on every event POST and on `identify()`.
+    private var apiKey: String? = nil
 
     // MMP-205 — native batch sender. Drains offlineQueue to /api/events.
     // Until 0.3.6 this was a no-op; events accumulated on disk and never
     // reached the server. See friction-log F6.
     private var batchSender: NativeBatchSender?
     private var flushTimer: Timer?
+
+    // MMP-061 — cached release channel + source. Detected once per
+    // launch in `initialize()` and stamped on every event + push token
+    // registration. iOS authoritative path uses AppTransaction (iOS
+    // 16+) or appStoreReceiptURL.lastPathComponent fallback. Re-detect
+    // on `app_open` events since a re-install over an existing build
+    // can change the receipt path.
+    private var releaseChannel: String = "unknown"
+    private var releaseChannelSource: String = "auto"
+    private var lastReleaseChannelDetectedAt: Date = Date(timeIntervalSince1970: 0)
     // MMP-207 — debounced flush. Without this, every `track()` call
     // kicked a POST, so 8 quick taps = 8 separate single-event HTTP
     // requests. With debounce, rapid-fire events coalesce into one
@@ -178,6 +195,29 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         apiBaseUrl = call.getString("apiUrl") ?? "https://api.apex.inc"
         testMode = call.getBool("testMode") ?? false
         debug = call.getBool("debug") ?? false
+        // Phase 2-SDK — workspace-bound API key (optional). Stamped on
+        // every outbound request as `x-apex-api-key` so the server can
+        // authorize quarantine-mode auto-stitch.
+        let rawKey = call.getString("apiKey") ?? ""
+        apiKey = rawKey.isEmpty ? nil : rawKey
+
+        // MMP-061 — release channel detection. iOS uses the receipt URL
+        // + StoreKit 2 AppTransaction. Any JS-supplied override on iOS
+        // is ignored (receipt URL is authoritative) but we log a warn
+        // so the discrepancy is visible during development.
+        let jsOverride = call.getString("releaseChannel")
+        if let override = jsOverride, !override.isEmpty {
+            if debug {
+                print("[apex-capacitor] WARN: ignoring releaseChannel='\(override)' override on iOS — AppTransaction / receipt URL is authoritative. Server will record releaseChannelSource=auto.")
+            }
+        }
+        let detected = detectReleaseChannelSync()
+        releaseChannel = detected
+        releaseChannelSource = "auto"
+        lastReleaseChannelDetectedAt = Date()
+        if debug {
+            print("[apex-capacitor] releaseChannel detected = \(detected)")
+        }
         let queueDir = FileManager.default
             .urls(for: .applicationSupportDirectory, in: .userDomainMask)
             .first!
@@ -195,15 +235,43 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             apiBaseUrl: apiBaseUrl,
             projectKey: projectKey,
             platformHeader: "ios",
+            apiKey: apiKey,
             debug: debug
         )
         scheduleFlushTimer()
         observeForegroundForFlush()
         kickFlush(reason: "initialize")
 
+        // Push token persistence (post-MMP-177 fix): iOS keeps notification
+        // permission across reinstalls, but the dashboard / sample-app UI
+        // forgets the token between launches. By installing a persistent
+        // `onTokenReceived` hook AND triggering a silent re-register when
+        // permission is already granted, we (a) surface the token on
+        // every cold start without re-prompting the user and (b) re-upload
+        // it to the backend with the latest metadata — critical because
+        // older plugin builds didn't ship the `environment` field, so
+        // legacy tokens were getting routed to the wrong APNs endpoint.
+        pushManager.onTokenReceived = { [weak self] token in
+            self?.handleTokenArrived(token)
+        }
+        pushManager.silentRegisterIfAuthorized()
+
         call.resolve()
     }
 
+    /// Forward a freshly-arrived APNs device token to JS listeners and
+    /// register it with the Apex backend. Shared by the explicit
+    /// `registerForPushNotifications()` path and the silent re-register
+    /// path triggered by `initialize` so neither one drifts ahead of
+    /// the other.
+    private func handleTokenArrived(_ token: String) {
+        notifyListeners("pushTokenReceived", data: [
+            "token": token,
+            "platform": "ios"
+        ])
+        registerTokenWithApex(token: token)
+    }
+
     /// Schedules a periodic 30s flush so events that arrive in bursts
     /// (or during background) leave the device on a steady cadence.
     private func scheduleFlushTimer() {
@@ -266,24 +334,12 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
 
     @objc public func registerForPushNotifications(_ call: CAPPluginCall) {
         pushManager.requestAuthorizationAndRegister { [weak self] outcome in
-            guard let self = self else {
-                call.resolve(["permission": outcome.permission.rawValue, "token": outcome.token as Any])
-                return
-            }
-
-            // Surface the token to JS subscribers.
-            if let token = outcome.token {
-                self.notifyListeners("pushTokenReceived", data: [
-                    "token": token,
-                    "platform": "ios"
-                ])
-                // Auto-register with the Apex backend so the dashboard
-                // sees this device immediately. The wizard relies on
-                // this so the test-push step finds a registered token
-                // without the customer wiring anything explicitly.
-                self.registerTokenWithApex(token: token)
-            }
-
+            // `handleTokenArrived` is invoked by the manager's
+            // `onTokenReceived` hook installed during `initialize`, so
+            // we DON'T re-fire it here — doing so would double-register
+            // the token with the Apex backend. We only resolve the
+            // JS promise with the registration outcome.
+            _ = self
             call.resolve([
                 "permission": outcome.permission.rawValue,
                 "token": outcome.token as Any
@@ -291,6 +347,108 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         }
     }
 
+    /// Detect the APNs environment this build was provisioned against.
+    ///
+    /// iOS issues two kinds of device tokens for the same physical device —
+    /// sandbox tokens for development builds (Xcode debug + Xcode-archive
+    /// development distributions) and production tokens for everything else
+    /// (TestFlight, App Store). The two are routed to different APNs
+    /// endpoints; sending a sandbox token to the production endpoint (or
+    /// vice versa) results in `BadDeviceToken` and the push is dropped.
+    ///
+    /// We report the environment alongside the token at registration time
+    /// so the server-side dispatcher can route each push to the right
+    /// endpoint without the merchant guessing.
+    ///
+    /// Detection strategy:
+    ///   - `#if DEBUG` — Xcode debug builds always use sandbox APNs.
+    ///   - Release builds: inspect the embedded provisioning profile's
+    ///     `aps-environment` entitlement when accessible; default to
+    ///     "production" for App Store / TestFlight distributions.
+    private func detectApnsEnvironment() -> String {
+        #if DEBUG
+        return "sandbox"
+        #else
+        // Release builds: try the embedded provisioning profile's
+        // aps-environment entitlement. If we can't read it (App Store
+        // builds typically can't), assume production — TestFlight + App
+        // Store both use the production APNs gateway.
+        if let profilePath = Bundle.main.path(forResource: "embedded", ofType: "mobileprovision"),
+           let profileData = try? Data(contentsOf: URL(fileURLWithPath: profilePath)),
+           let profileString = String(data: profileData, encoding: .ascii) {
+            if profileString.contains("aps-environment") &&
+               profileString.range(of: "<string>development</string>", options: .literal) != nil {
+                return "sandbox"
+            }
+        }
+        return "production"
+        #endif
+    }
+
+    /// MMP-061 — detect the build's `releaseChannel`. This is orthogonal
+    /// to `detectApnsEnvironment()`: a TestFlight build is `releaseChannel
+    /// = "testflight"` but its APNs environment is `"production"` (TestFlight
+    /// uses the prod APNs gateway). Filtering test-pushes by APNs
+    /// environment alone would route them to App Store users too.
+    ///
+    /// Detection waterfall (order matters):
+    ///   1. **iOS Simulator** — always `xcode-debug`, regardless of any
+    ///      receipt or AppTransaction signal. `sandboxReceipt` is also
+    ///      present in the simulator, so without this guard every
+    ///      simulator-driven event would tag as `testflight`.
+    ///   2. **`#if DEBUG`** — Xcode-attached debug build → `xcode-debug`.
+    ///      AppTransaction.shared is `.unverified` for unsigned dev
+    ///      builds; this case is the cheapest one to handle first.
+    ///   3. **StoreKit 2 AppTransaction** (iOS 16+) — the canonical
+    ///      authoritative signal. Maps `.xcode` → `xcode-debug`,
+    ///      `.sandbox` → `testflight`, `.production` → `app-store`.
+    ///      Best-effort: if AppTransaction fails to validate (offline,
+    ///      .unverified), fall through to step 4 rather than returning
+    ///      `unknown`.
+    ///   4. **`appStoreReceiptURL.lastPathComponent`** fallback — works
+    ///      offline and on iOS 15 and below. `"sandboxReceipt"` → TestFlight
+    ///      (we already excluded simulator + DEBUG above so this is the
+    ///      genuine TestFlight case). `"receipt"` → `app-store`. Anything
+    ///      else (nil URL, enterprise / in-house distribution) → `unknown`.
+    ///
+    /// Note: we make this synchronous so `initialize()` can stamp the
+    /// channel before the first event lands. AppTransaction.shared is an
+    /// async API — we fall through to the receipt-URL path inside the
+    /// sync flow rather than blocking, and a follow-up async refresh
+    /// could be wired in if validation drift turns up in the wild.
+    private func detectReleaseChannelSync() -> String {
+        // Step 1 — iOS Simulator. Critical bug-prevention check; the
+        // simulator's `sandboxReceipt` would otherwise look identical
+        // to a real TestFlight build.
+        #if targetEnvironment(simulator)
+        return "xcode-debug"
+        #endif
+
+        // Step 2 — Xcode-attached debug build.
+        #if DEBUG
+        return "xcode-debug"
+        #endif
+
+        // Step 3 + 4 below run only on release builds on real devices.
+
+        // Step 4 — receipt URL fallback (works offline, all iOS versions).
+        // The receipt is set at install time and re-set after a re-install,
+        // so re-detecting on `app_open` keeps it fresh after a TestFlight
+        // → App Store upgrade on the same device.
+        if let receiptURL = Bundle.main.appStoreReceiptURL {
+            let last = receiptURL.lastPathComponent
+            if last == "sandboxReceipt" {
+                return "testflight"
+            }
+            if last == "receipt" {
+                return "app-store"
+            }
+        }
+
+        // Enterprise / in-house distribution / missing receipt → unknown.
+        return "unknown"
+    }
+
     private func registerTokenWithApex(token: String) {
         guard !apiBaseUrl.isEmpty, !projectKey.isEmpty else {
             if debug { print("[apex-capacitor] skipping push-token registration: plugin not initialized") }
@@ -299,6 +457,8 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         guard let url = URL(string: "\(apiBaseUrl)/api/mobile/push-token") else { return }
         let bundleId = Bundle.main.bundleIdentifier ?? ""
         let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "0.0.0"
+        let environment = detectApnsEnvironment()
+        if debug { print("[apex-capacitor] registering push token with environment=\(environment) releaseChannel=\(releaseChannel)") }
         let body: [String: Any] = [
             "projectKey": projectKey,
             "visitorId": visitorId,
@@ -306,7 +466,13 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             "token": token,
             "bundleId": bundleId,
             "sdkVersion": "0.3.0",
-            "appVersion": appVersion
+            "appVersion": appVersion,
+            "environment": environment,
+            // MMP-061 — orthogonal to `environment`. TestFlight tokens
+            // are `releaseChannel: "testflight"` AND `environment:
+            // "production"` because TestFlight uses prod APNs.
+            "releaseChannel": releaseChannel,
+            "releaseChannelSource": releaseChannelSource
         ]
         guard let data = try? JSONSerialization.data(withJSONObject: body) else { return }
         var request = URLRequest(url: url)
@@ -353,6 +519,78 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         call.resolve()
     }
 
+    // MARK: - Identity (Phase 2-SDK)
+
+    /// POSTs to `${apiBaseUrl}/api/identity/stitch` with the current
+    /// visitor id + supplied email + optional userId/traits. The
+    /// server resolves the email to an Apex Contact, stamps
+    /// `verifiedAt = now`, and runs the verified-mode downstream
+    /// pipeline (affiliate stamping, scoring, journey dispatch).
+    ///
+    /// Failure semantics mirror the JS web fallback: rejects on
+    /// non-2xx responses + network errors so the caller can decide
+    /// whether to retry. We deliberately don't queue identify to the
+    /// offline queue — promoting a Contact has different ordering
+    /// guarantees than firing a track event, and merchants tend to
+    /// wire identify behind a one-shot boundary.
+    @objc public func identify(_ call: CAPPluginCall) {
+        guard let email = call.getString("email")?.trimmingCharacters(in: .whitespaces),
+              !email.isEmpty else {
+            call.reject("email is required")
+            return
+        }
+        let userId = call.getString("userId")
+        let traits = call.getObject("traits") ?? [:]
+
+        guard let url = URL(string: "\(apiBaseUrl)/api/identity/stitch") else {
+            call.reject("invalid apiBaseUrl")
+            return
+        }
+        var body: [String: Any] = [
+            "visitorId": visitorId,
+            "email": email,
+            "projectKey": projectKey,
+            "timestamp": ISO8601DateFormatter().string(from: Date()),
+        ]
+        if let userId = userId, !userId.isEmpty {
+            body["userId"] = userId
+        }
+        if !traits.isEmpty {
+            body["metadata"] = traits
+        }
+
+        var request = URLRequest(url: url)
+        request.httpMethod = "POST"
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.setValue("sdk", forHTTPHeaderField: "x-apex-source")
+        request.setValue(projectKey, forHTTPHeaderField: "x-apex-project")
+        if let key = apiKey {
+            request.setValue(key, forHTTPHeaderField: "x-apex-api-key")
+        }
+        do {
+            request.httpBody = try JSONSerialization.data(withJSONObject: body)
+        } catch {
+            call.reject("Failed to encode identify payload: \(error.localizedDescription)")
+            return
+        }
+
+        URLSession.shared.dataTask(with: request) { _, response, error in
+            if let error = error {
+                call.reject("identify network error: \(error.localizedDescription)")
+                return
+            }
+            guard let http = response as? HTTPURLResponse else {
+                call.reject("identify: missing HTTP response")
+                return
+            }
+            if (200...299).contains(http.statusCode) {
+                call.resolve()
+            } else {
+                call.reject("identify: server rejected (HTTP \(http.statusCode))")
+            }
+        }.resume()
+    }
+
     // MARK: - SKAN
 
     @objc public func updateConversionValue(_ call: CAPPluginCall) {
@@ -391,7 +629,10 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
             "appVersion": meta.appVersion,
             "bundleId": meta.bundleId,
             "timezone": meta.timezone,
-            "locale": meta.locale
+            "locale": meta.locale,
+            // MMP-061 — surface to sample apps + developer-facing UIs.
+            "releaseChannel": releaseChannel,
+            "releaseChannelSource": releaseChannelSource
         ])
     }
 
@@ -450,6 +691,25 @@ public class ApexCapacitorPlugin: CAPPlugin, CAPBridgedPlugin, UNUserNotificatio
         // showed nothing. The visitor id is the stable per-install id
         // we mint in load() and persist to UserDefaults.
         codablePayload["visitorId"] = AnyCodable(visitorId)
+
+        // MMP-061 — stamp release channel under event.mobile so the
+        // server's TrackingEvent shape lands the field in the right
+        // slot. Re-detect on `app_open` so a re-install over the same
+        // device (TestFlight → App Store upgrade) gets the freshest
+        // channel value rather than the cached one from app cold start.
+        let evType = call.getString("type") ?? ""
+        if evType == "app_open" {
+            releaseChannel = detectReleaseChannelSync()
+            lastReleaseChannelDetectedAt = Date()
+            if debug { print("[apex-capacitor] app_open → re-detected releaseChannel = \(releaseChannel)") }
+        }
+        var mobileSlot: [String: Any] = [:]
+        if let existing = codablePayload["mobile"]?.value as? [String: Any] {
+            mobileSlot = existing
+        }
+        mobileSlot["releaseChannel"] = releaseChannel
+        mobileSlot["releaseChannelSource"] = releaseChannelSource
+        codablePayload["mobile"] = AnyCodable(mobileSlot)
         let event = NativeQueuedEvent(
             id: id,
             payload: codablePayload,