@bubblsdk/react-native-sdk 4.1.7 → 5.0.0-alpha.2

package/ios-sdk/BubblSDK/BubblPermissions.swift

@@ -0,0 +1,79 @@
+import Foundation
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// Where the device stands on the permissions Bubbl uses. The same as Android's.
+public struct BubblPermissionStatus: Sendable, Equatable {
+    public enum Notifications: Sendable, Equatable { case granted, denied, notDetermined }
+    public enum Location: Sendable, Equatable { case always, whenInUse, denied, notDetermined }
+
+    public let notifications: Notifications
+    public let location: Location
+    /// Precise rather than approximate location (geofences need it).
+    public let preciseLocation: Bool
+
+    init(_ status: PermissionStatus) {
+        notifications = switch status.notifications {
+        case .granted: .granted
+        case .denied: .denied
+        case .notDetermined: .notDetermined
+        }
+        location = switch status.location {
+        case .always: .always
+        case .whenInUse: .whenInUse
+        case .denied: .denied
+        case .notDetermined: .notDetermined
+        }
+        preciseLocation = status.preciseLocation
+    }
+}
+
+/// The permissions Bubbl uses (`Bubbl.permissions`): where they stand, and asking for them. Asking
+/// shows the privacy view first when the dashboard says to, then the system's prompt; it works from
+/// anywhere in the app. iOS prompts for each permission once: after a refusal, `openSettings()`.
+public struct BubblPermissions: Sendable {
+    /// Where the device stands, as last looked (at start, when the app comes to the front, after
+    /// asking); nil before `Bubbl.start`, and where Bubbl isn't supported (below iOS 17).
+    public func status() -> BubblPermissionStatus? {
+        Bubbl.backend.permissionStatus()
+    }
+
+    /// Notifications: the privacy view if the dashboard says so, then the system prompt.
+    public func requestNotifications() async -> BubblPermissionStatus? {
+        await request(.notifications, "permissions.requestNotifications")
+    }
+
+    /// Location: the privacy view if the dashboard says so, then the system prompt; with `always`,
+    /// the second step to "Always" too (geofences with the app closed).
+    public func requestLocation(always: Bool = false) async -> BubblPermissionStatus? {
+        await request(always ? .locationAlways : .locationWhenInUse, "permissions.requestLocation")
+    }
+
+    /// `requestNotifications()` for code that can't await; `completion` runs on the main thread.
+    public func requestNotifications(completion: @escaping @MainActor @Sendable (BubblPermissionStatus?) -> Void) {
+        Task {
+            let result = await requestNotifications()
+            await MainActor.run { completion(result) }
+        }
+    }
+
+    /// `requestLocation(always:)` for code that can't await; `completion` runs on the main thread.
+    public func requestLocation(always: Bool, completion: @escaping @MainActor @Sendable (BubblPermissionStatus?) -> Void) {
+        Task {
+            let result = await requestLocation(always: always)
+            await MainActor.run { completion(result) }
+        }
+    }
+
+    /// The app's page in the system's Settings, for a permission the user refused (one of the app's
+    /// own, like the camera, too). Works before `Bubbl.start`: it needs nothing of Bubbl's. Opens on
+    /// the main thread, whichever thread this is called from.
+    public func openSettings() {
+        Bubbl.backend.openSettings()
+    }
+
+    private func request(_ request: PermissionRequest, _ call: String) async -> BubblPermissionStatus? {
+        await Bubbl.backend.requestPermission(request, call)
+    }
+}

package/ios-sdk/BubblSDK/BubblTestDeviceResult.swift

@@ -0,0 +1,10 @@
+import Foundation
+
+/// What `Bubbl.registerTestDevice` came to: approved as a Sandbox test device, or not, and why.
+public struct BubblTestDeviceResult: Sendable, Equatable {
+    public let approved: Bool
+    /// Why not, when not approved, to show whoever typed the code: the server's words (a wrong,
+    /// used or expired code, the Sandbox's test devices all taken) or the SDK's (before `start`,
+    /// no network, below iOS 17). Nil when approved.
+    public let message: String?
+}

package/ios-sdk/BubblSDK/Engine/BackgroundRefresh.swift

@@ -0,0 +1,92 @@
+#if os(iOS)
+import BackgroundTasks
+import Foundation
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// Background app refresh (optional): iOS wakes the app now and then, and Bubbl sends what's queued
+/// and refreshes its config, so events don't wait for the app's next run. Only when the app allows
+/// it in its Info.plist: "tech.bubbl.sdk.refresh" in BGTaskSchedulerPermittedIdentifiers, and
+/// "fetch" in UIBackgroundModes (Background fetch). Without those, events go when the app goes to
+/// the background and on its next run, as before.
+///
+/// iOS wants the handler registered before launch finishes (later is an exception), which is why
+/// it's done from BubblLaunch's +load, before main().
+@available(iOS 17, *)
+enum BackgroundRefresh {
+    static let identifier = "tech.bubbl.sdk.refresh"
+
+    private static let lock = NSLock()
+    nonisolated(unsafe) private static var registered = false
+
+    /// The app lets Bubbl refresh in the background.
+    static var declared: Bool {
+        let identifiers = Bundle.main.object(forInfoDictionaryKey: "BGTaskSchedulerPermittedIdentifiers") as? [String] ?? []
+        let modes = Bundle.main.object(forInfoDictionaryKey: "UIBackgroundModes") as? [String] ?? []
+        return identifiers.contains(identifier) && modes.contains("fetch")
+    }
+
+    /// From +load. (Not main-actor code: iOS runs the handler on a queue of its own.)
+    static func register() {
+        guard declared else { return }
+        let done = BGTaskScheduler.shared.register(forTaskWithIdentifier: identifier, using: nil) { task in
+            EngineHost.shared.backgroundRefresh(task)
+        }
+        lock.sync { registered = done }
+    }
+
+    /// Asks iOS for the next refresh, no sooner than half an hour from now (iOS picks the time).
+    static func schedule() {
+        guard lock.sync({ registered }) else { return }
+        let request = BGAppRefreshTaskRequest(identifier: identifier)
+        request.earliestBeginDate = Date(timeIntervalSinceNow: 30 * 60)
+        do {
+            try BGTaskScheduler.shared.submit(request)
+        } catch {
+            BubblLog.debug("Background refresh not scheduled (\(type(of: error)))")
+        }
+    }
+}
+
+@available(iOS 17, *)
+extension EngineHost {
+    /// iOS woke the app for a background refresh: the next one asked for, then the config, the
+    /// device, what's queued and segments sent (maintenance), within the time iOS gives.
+    func backgroundRefresh(_ task: BGTask) {
+        BackgroundRefresh.schedule()
+        // Launched in the background for this: Bubbl starts itself as the app last started it.
+        if current == nil { applicationDidFinishLaunching() }
+
+        let handed = Handed(task)
+        let finished = Once()
+        guard let core = current, core.isActive else {
+            finished.run { handed.value.setTaskCompleted(success: true) }
+            return
+        }
+        let work = Task {
+            _ = await core.maintenance()
+            finished.run { handed.value.setTaskCompleted(success: true) }
+        }
+        task.expirationHandler = {
+            work.cancel()
+            finished.run { handed.value.setTaskCompleted(success: false) }
+        }
+    }
+}
+
+/// Runs its body once, whichever caller gets there first.
+@available(iOS 17, *)
+final class Once: @unchecked Sendable {
+    private let lock = NSLock()
+    private var done = false
+
+    func run(_ body: () -> Void) {
+        let first: Bool = lock.sync {
+            defer { done = true }
+            return !done
+        }
+        if first { body() }
+    }
+}
+#endif

package/ios-sdk/BubblSDK/Engine/EngineHost+Geofences.swift

@@ -0,0 +1,177 @@
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// Geofencing in the host, as Android's GeofenceWork: what CoreLocation reports becomes saved
+/// transitions, sent at once in the time iOS gives the event; checks (fetch when due, watch the
+/// nearest, re-watch after a failure or a change of permission) run as work, retried with backoff.
+@available(iOS 17, *)
+extension EngineHost {
+    static func regionMonitor() -> any RegionMonitor {
+        #if os(iOS)
+        CoreLocationRegionMonitor()
+        #else
+        InactiveRegionMonitor()
+        #endif
+    }
+
+    /// Makes CoreLocation's managers now, on the main thread: an app relaunched for a region event
+    /// gets the event only once they exist.
+    func startLocation() {
+        #if os(iOS)
+        if Thread.isMainThread {
+            MainActor.assumeIsolated { LocationService.shared.activate() }
+        } else {
+            Task { @MainActor in LocationService.shared.activate() }
+        }
+        #endif
+    }
+
+    /// Check the geofences soon: fetch them if due (or `force`), from `fix` or a fresh one
+    /// (`precise` for a polygon), watching them again first if `rewatch`. A check asked for while
+    /// one runs replaces any other waiting.
+    func checkGeofences(force: Bool = false, precise: Bool = false, rewatch: Bool = false, fix: Fix? = nil) {
+        #if os(iOS)
+        submit("geofences.check") { core in
+            await self.runCheck(core, force: force, precise: precise, rewatch: rewatch, fix: fix)
+        }
+        #endif
+    }
+
+    /// The app came to the front: where iOS isn't watching the geofences, they're checked from
+    /// fixes while it's open.
+    func appOpenedForLocation() {
+        #if os(iOS)
+        guard let core = current, core.locationActive else { return }
+        Task { @MainActor in LocationService.shared.startInUseUpdates() }
+        checkGeofences()
+        #endif
+    }
+
+    #if os(iOS)
+    @MainActor
+    func appWentToTheBackForLocation() {
+        LocationService.shared.stopInUseUpdates()
+    }
+
+    // MARK: - From LocationService (main thread)
+
+    /// CoreLocation says the device entered or left Bubbl's regions `ids`.
+    @MainActor
+    func regionEvent(_ ids: [String], entered: Bool, fix: Fix?, deviceTimeMillis: Int64) {
+        guard let core = current else { return }
+        let time = BackgroundTime("tech.bubbl.sdk.geofence")
+        Task {
+            let outcome = await core.regionEvent(ids, entered: entered, fix: fix, deviceTimeMillis: deviceTimeMillis)
+            await act(on: outcome, core, fix: nil)
+            time.end()
+        }
+    }
+
+    /// A fix: a significant change (`osWatches`), or one while the app is open with location only
+    /// while in use.
+    @MainActor
+    func locationFix(_ fix: Fix, osWatches: Bool) {
+        guard let core = current else { return }
+        let time = BackgroundTime("tech.bubbl.sdk.location")
+        Task {
+            let outcome = await core.locationFix(fix, osWatches: osWatches)
+            await act(on: outcome, core, fix: fix)
+            time.end()
+        }
+    }
+
+    /// CoreLocation couldn't watch a region: the next check watches them all again (not now, which
+    /// would go round and round while iOS keeps refusing).
+    @MainActor
+    func watchFailed() {
+        guard let core = current else { return }
+        Task { try? await core.geofences.watchFailed() }
+    }
+
+    /// The user changed the app's location permission.
+    @MainActor
+    func locationAccessChanged(_ access: LocationAccess) {
+        guard let core = current, core.locationActive else { return }
+        switch access {
+        case .none:
+            Task { await LocationService.shared.stopAll() }
+        case .whenInUse, .always:
+            if UIApplication.shared.applicationState != .background { LocationService.shared.startInUseUpdates() }
+            checkGeofences(rewatch: true)
+        }
+    }
+
+    // MARK: - Work
+
+    /// Android's CheckGeofencesWorker, with the fix from CoreLocation.
+    func runCheck(_ core: EngineCore, force: Bool, precise: Bool, rewatch: Bool, fix: Fix?) async -> WorkOutcome {
+        guard core.locationActive else { return .done }
+        let (access, osWatches) = await MainActor.run { (LocationService.shared.access, LocationService.shared.osWatches) }
+        guard access != .none else { return .done }
+
+        let current: Fix?
+        if let fix { current = fix } else { current = await LocationService.shared.currentFix(precise: precise) }
+        guard let current else {
+            BubblLog.debug("Geofence check: no location fix")
+            return .done
+        }
+
+        let result = await core.checkGeofences(fix: current, force: force, rewatch: rewatch, osWatches: osWatches)
+        if core.hasPendingTransitions { await sendTransitionsNow(core) }
+        return result
+    }
+
+    /// What an event or a fix led to: its transitions sent now, and a check if it asked for one,
+    /// all in the time iOS gave the event.
+    private func act(on outcome: Outcome, _ core: EngineCore, fix: Fix?) async {
+        for transition in outcome.transitions {
+            BubblEvents.shared.emit(transition.enter ? .geofenceEntered(locationId: transition.locationId) : .geofenceExited(locationId: transition.locationId))
+        }
+        if !outcome.transitions.isEmpty { await sendTransitionsNow(core) }
+        guard outcome.refresh || outcome.needsFix else { return }
+        let checked = await runCheck(core, force: outcome.refresh, precise: outcome.needsFix, rewatch: false, fix: outcome.needsFix ? nil : fix)
+        if case .retry = checked { checkGeofences(force: outcome.refresh, precise: outcome.needsFix) }
+    }
+
+    /// Send the saved transitions now; what couldn't go is retried, with backoff, as work.
+    private func sendTransitionsNow(_ core: EngineCore) async {
+        if case .retry = await sendTransitions(core) {
+            submit("geofences.transitions") { await self.sendTransitions($0) }
+        }
+    }
+
+    private func sendTransitions(_ core: EngineCore) async -> WorkOutcome {
+        let sent = await core.sendTransitions()
+        await arrived(sent.notifications, core)
+        if sent.recheck { checkGeofences(force: true) }
+        return sent.outcome
+    }
+    #endif
+}
+
+#if canImport(UIKit) && !os(watchOS)
+/// The few seconds iOS gives to finish something in the background, asked for when it starts and
+/// handed back when it's done (or when iOS says time is up).
+@available(iOS 17, *)
+@MainActor
+final class BackgroundTime {
+    private var id = UIBackgroundTaskIdentifier.invalid
+
+    init(_ name: String) {
+        id = UIApplication.shared.beginBackgroundTask(withName: name) { [weak self] in
+            MainActor.assumeIsolated { self?.end() }
+        }
+    }
+
+    func end() {
+        guard id != .invalid else { return }
+        UIApplication.shared.endBackgroundTask(id)
+        id = .invalid
+    }
+}
+#endif

package/ios-sdk/BubblSDK/Engine/EngineHost+Privacy.swift

@@ -0,0 +1,65 @@
+import Foundation
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// The user's decisions (Bubbl.setConsent, optOut, deleteMyData, setLocationEnabled) in the host:
+/// the engine changes its state and stops what it must (EngineCore's PrivacyControls); the host
+/// cancels its waiting work and runs what each needs, retried until done.
+@available(iOS 17, *)
+extension EngineHost {
+    /// Consent given (again): everything consent allows starts, geofences fetched afresh.
+    func consentGiven(_ core: EngineCore) {
+        resume(core)
+        if core.locationActive { checkGeofences(force: true) }
+    }
+
+    /// The user opted out: nothing more runs, what's queued goes, and the server is told once.
+    func optOut(_ core: EngineCore) {
+        Task {
+            await runner.cancelAll()
+            do {
+                if try await core.optOut() { submit("privacy.withdrawn") { await $0.consentWithdrawn() } }
+            } catch {
+                BubblLog.warning("Bubbl.optOut can't be saved until the device is unlocked: ask again then")
+            }
+        }
+    }
+
+    /// The user asked for their data to be erased: stopped now, erased (server, then here) as work.
+    func erase(_ core: EngineCore) {
+        Task {
+            await runner.cancelAll()
+            do {
+                try await core.requestErasure()
+                submit("privacy.erase") { await $0.eraseDevice() }
+            } catch {
+                BubblLog.warning("Bubbl.deleteMyData can't be saved until the device is unlocked: ask again then")
+            }
+        }
+    }
+
+    /// Location (geofences) on or off; the rest carries on.
+    func setLocationEnabled(_ enabled: Bool, _ core: EngineCore) {
+        Task {
+            do {
+                guard try await core.setLocationEnabled(enabled), enabled else { return }
+                checkGeofences(force: true)
+                appOpenedForLocation()
+            } catch {
+                BubblLog.warning("Bubbl.setLocationEnabled can't be saved until the device is unlocked: ask again then")
+            }
+        }
+    }
+
+    /// At every start: an erasure or an opt-out a killed app didn't finish telling the server about
+    /// carries on (the work runner isn't kept between launches).
+    func resumePrivacyWork(_ core: EngineCore) {
+        guard let state = core.privacy.state else { return }
+        if state.pendingDelete {
+            submit("privacy.erase") { await $0.eraseDevice() }
+        } else if state.consent == false {
+            submit("privacy.withdrawn") { await $0.consentWithdrawn() }
+        }
+    }
+}

package/ios-sdk/BubblSDK/Engine/EngineHost+Push.swift

@@ -0,0 +1,154 @@
+import Foundation
+#if canImport(UserNotifications)
+import UserNotifications
+#endif
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// Shows a notification inside the app: Bubbl's notification screen (M2 slice 10), or the app's
+/// own listener. True when it was shown there, so the system's banner isn't needed as well.
+@available(iOS 17, *)
+protocol NotificationPresenting: Sendable {
+    func present(_ notification: JSONValue, opened: Bool) async -> Bool
+}
+
+/// Until the notification screen (slice 10): nothing is shown in the app, so a push in front keeps
+/// the system's banner, and a tap just opens the app.
+@available(iOS 17, *)
+struct SystemAlertPresenter: NotificationPresenting {
+    func present(_ notification: JSONValue, opened: Bool) async -> Bool {
+        BubblLog.debug("A notification to show\(opened ? " (tapped)" : "")")
+        return false
+    }
+}
+
+/// A value the compiler can't see is safe to hand across: the completion handlers iOS passes the
+/// notification delegate, which are called exactly once, from any thread.
+@available(iOS 17, *)
+struct Handed<Value>: @unchecked Sendable {
+    let value: Value
+    init(_ value: Value) { self.value = value }
+}
+
+/// Push in the host: the APNs device token, and Bubbl's pushes as iOS hands them to the app (with
+/// the app in front, and when their notification is tapped). The automatic integration
+/// (PushIntegration) and the manual hooks on Bubbl both come here.
+@available(iOS 17, *)
+extension EngineHost {
+    /// The APNs device token iOS gave the app: kept with its environment, and sent with PUT /device
+    /// when it's new or changed.
+    func pushTokenReceived(_ deviceToken: Data) {
+        let hex = deviceToken.map { String(format: "%02x", $0) }.joined()
+        let token = PushToken(token: hex, type: "apns", environment: Self.apnsEnvironment)
+        guard platform.pushToken() != token else { return }
+        platform.setPushToken(token)
+        BubblLog.info("Got the device's APNs token (\(token.environment ?? "unknown environment"))")
+        submit("device") { await $0.syncDevice() }
+    }
+
+    /// Which APNs environment this build's tokens belong to: the provisioning profile's
+    /// aps-environment; no profile (the App Store's own signing) is production; the Simulator's
+    /// tokens are sandbox ones.
+    static let apnsEnvironment: String = {
+        #if targetEnvironment(simulator)
+        return "sandbox"
+        #else
+        guard let url = Bundle.main.url(forResource: "embedded", withExtension: "mobileprovision"),
+              let profile = try? Data(contentsOf: url)
+        else { return "production" }
+        return ProvisioningProfile.apnsEnvironment(profile) ?? "production"
+        #endif
+    }()
+
+    /// A push's payload as JSON: its top level, where Bubbl's data sits beside aps. Values that
+    /// aren't JSON are left out.
+    static func pushData(_ userInfo: [AnyHashable: Any]) -> [String: JSONValue] {
+        var data: [String: JSONValue] = [:]
+        for (key, value) in userInfo {
+            if let key = key as? String, let json = JSONValue(app: value) { data[key] = json }
+        }
+        return data
+    }
+
+    /// A notification to show now: `received` (it has just arrived for the first time) tells the
+    /// app's event listeners; the app's notification listener may take it (then Bubbl shows
+    /// nothing); otherwise Bubbl's screen. True when it was shown in the app.
+    func show(_ json: JSONValue, received: Bool, opened: Bool) async -> Bool {
+        guard let notification = BubblNotification(json) else { return false }
+        let message = BubblMessage(notification)
+        if received { BubblEvents.shared.emit(.notificationReceived(message)) }
+        if let listener = notificationListener, await MainActor.run(body: { listener(message) }) { return true }
+        return await presenter.present(json, opened: opened)
+    }
+
+    /// Notifications a geofence or a pull brought, each shown the first time it arrives.
+    func arrived(_ notifications: [JSONValue], _ core: EngineCore) async {
+        for notification in notifications {
+            if case .show(let json, let received) = await core.notificationArrived(notification, opened: false) {
+                _ = await show(json, received: received, opened: false)
+            }
+        }
+    }
+
+    /// The events of a notification's life, recorded for Bubbl and told to the app's listeners.
+    func notificationEvents(_ core: EngineCore) -> NotificationEvents {
+        NotificationEvents(
+            observe: { type, notification in
+                BubblEvents.event(type, BubblMessage(notification)).map(BubblEvents.shared.emit)
+            },
+            enqueue: { type, data in try await core.events.enqueue(type, data: data) }
+        )
+    }
+
+    #if canImport(UserNotifications)
+    /// The system banner, list entry and sound: how iOS shows a push in front when asked to.
+    static let systemPresentation: UNNotificationPresentationOptions = [.banner, .list, .sound]
+
+    /// A Bubbl push arrived with the app in front: how iOS should show it. Bubbl's screen shows a
+    /// campaign's notification when it can (then no banner); a test push is a plain banner; a
+    /// notification already shown, or anything while Bubbl isn't active, isn't shown again.
+    func presentation(forArriving data: [String: JSONValue]) async -> UNNotificationPresentationOptions {
+        // Started later in this launch (a wrapper's JavaScript or Dart not run yet): the system
+        // shows it, rather than swallowing a push.
+        guard let core = current else { return Self.systemPresentation }
+
+        switch await core.receivedPush(data, opened: false) {
+        case .show(let notification, let received):
+            return await show(notification, received: received, opened: false) ? [] : Self.systemPresentation
+        case .test:
+            return Self.systemPresentation
+        case .fetchFailed:
+            // The alert has its title and body; a tap fetches it again.
+            return Self.systemPresentation
+        case .nothing:
+            return []
+        }
+    }
+    #endif
+
+    /// A Bubbl push's notification was tapped: its notification opens (fetched first if it came
+    /// without it; retried with backoff when that fails). A test push just opens the app.
+    func pushOpened(_ data: [String: JSONValue]) async {
+        guard let core = current else { return }
+
+        switch await core.receivedPush(data, opened: true) {
+        case .show(let notification, let received):
+            _ = await show(notification, received: received, opened: true)
+        case .fetchFailed(let id, _):
+            submit("notifications.fetch.\(id)") { core in
+                switch await core.receivedPush(data, opened: true) {
+                case .show(let notification, let received):
+                    _ = await self.show(notification, received: received, opened: true)
+                    return .done
+                case .fetchFailed(_, let failure):
+                    return await core.handle(failure, "Fetching a notification")
+                case .test, .nothing:
+                    return .done
+                }
+            }
+        case .test, .nothing:
+            break
+        }
+    }
+}