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

package/ios-sdk/BubblSDK/Bubbl.swift

@@ -0,0 +1,308 @@
+import Foundation
+#if canImport(UserNotifications)
+import UserNotifications
+#endif
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// Bubbl, for an iOS app: the same functions as Android's `tech.bubbl.sdk.Bubbl`
+/// (docs/PUBLIC_API.md). Two steps to install: add the package, and in
+/// `application(_:didFinishLaunchingWithOptions:)` (or the SwiftUI `App`'s init)
+///
+///     Bubbl.start(apiKey: "pk_live_…", options: BubblOptions(baseUrl: "https://…"))
+///
+/// Every call is safe from any thread. Calls before `start` do nothing (and log a warning), except
+/// `permissions.openSettings()`, which needs nothing of Bubbl's. Bubbl never stops the app: a mistake (an empty key, an http:// URL) is logged, not thrown.
+///
+/// Bubbl works on iOS 17 and later. An app supporting older versions can still include it: on
+/// those phones `isSupported` is false and every call does nothing (see `isSupported`).
+public enum Bubbl {
+    /// This SDK's version.
+    public static let sdkVersion = BubblVersion.sdk
+
+    /// Whether Bubbl works on this device (iOS 17 and later). When false, `start` logs that it
+    /// does nothing here and returns: nothing is installed or sent, nothing prompts, no
+    /// notification delegate or background task is set up, and no location is used. Every other
+    /// call does nothing too, permission calls report nil, notification listeners are never
+    /// called, and `diagnostics()` says `supported: false`.
+    public static var isSupported: Bool { backend.isSupported }
+
+    // MARK: - Starting
+
+    /// Start Bubbl. Call once per launch, early (so background launches for a geofence or a push
+    /// have it too); calling again with the same key and options changes nothing.
+    public static func start(apiKey: String, options: BubblOptions) {
+        backend.start(apiKey: apiKey, options: options)
+    }
+
+    /// Start Bubbl with a device credential issued outside the app (installs provisioned ahead of
+    /// time, an app's own pairing flow) instead of an API key: the device never registers itself.
+    /// As `start(apiKey:options:)` otherwise, and called the same way at every launch. A different
+    /// credential than last time (or switching from an API key) starts afresh as a new device:
+    /// nothing kept from before is sent under the new one. If the server refuses the credential,
+    /// Bubbl stops and says so (`BubblEvent.credentialRejected`, diagnostics) until it's started
+    /// with a new one.
+    public static func start(credential: BubblCredential, options: BubblOptions) {
+        backend.start(credential: credential, options: options)
+    }
+
+    /// Stop Bubbl on this device until `start` is called again: nothing more runs; nothing is
+    /// dropped, and the server isn't told (unlike `optOut`).
+    public static func stop() {
+        backend.stop()
+    }
+
+    // MARK: - Consent and privacy
+
+    /// The user's answer, for apps started with `requireConsent` (and to give consent again after
+    /// an opt-out): true starts everything; false is the same as `optOut()`.
+    public static func setConsent(_ granted: Bool) {
+        backend.setConsent(granted)
+    }
+
+    /// Stop Bubbl for this user: nothing more is sent, shown or tracked, what's queued is dropped,
+    /// and the server is told.
+    public static func optOut() {
+        backend.optOut()
+    }
+
+    /// Erase this device and everything Bubbl recorded about it, on the server and here. It keeps
+    /// trying until it's done, and Bubbl stays off afterwards (`setConsent(true)` later starts
+    /// afresh, as a new device).
+    public static func deleteMyData() {
+        backend.deleteMyData()
+    }
+
+    /// Turn Bubbl's use of location (geofences) off, or on again; the rest carries on.
+    public static func setLocationEnabled(_ enabled: Bool) {
+        backend.setLocationEnabled(enabled)
+    }
+
+    // MARK: - Sandbox
+
+    /// Approve this device as a Sandbox test device with a registration code from the dashboard
+    /// (Test devices › Registration codes; each approves one device, within 24 hours), e.g. from a
+    /// hidden debug menu or a device farm's set-up. The other ways need no code in the app: the
+    /// dashboard's "Add a test device", or matching the code Bubbl logs at start in Sandbox.
+    /// `approved` once it is; otherwise `message` says why, to show whoever typed the code (a
+    /// wrong, used or expired code, the Sandbox's 25 test devices taken, before `start`, no
+    /// network). Also said in the log.
+    public static func registerTestDevice(_ code: String) async -> BubblTestDeviceResult {
+        await backend.registerTestDevice(code)
+    }
+
+    /// `registerTestDevice(_:)` for code that can't await; `completion` runs on the main thread.
+    public static func registerTestDevice(_ code: String, completion: @escaping @Sendable @MainActor (BubblTestDeviceResult) -> Void) {
+        Task {
+            let result = await registerTestDevice(code)
+            await MainActor.run { completion(result) }
+        }
+    }
+
+    // MARK: - Permissions
+
+    /// The permissions Bubbl uses: where they stand, and asking for them.
+    public static let permissions = BubblPermissions()
+
+    // MARK: - Targeting and events
+
+    /// The device's segments, for targeting campaigns (replaces any set before).
+    public static func setSegments(_ segments: [String]) {
+        backend.setSegments(segments)
+    }
+
+    /// Record an event of the app's own, for reports: a `name` of letters, digits and . _ : - (at
+    /// most 100), and up to 50 flat `properties` (text, numbers, true/false or nil).
+    public static func track(_ name: String, properties: [String: Any?] = [:]) {
+        backend.track(name, properties: properties)
+    }
+
+    // MARK: - Notifications
+
+    /// Have a say over each notification before Bubbl shows it: return true to show it yourself
+    /// (then report what happens with `reportDisplayed` and the others), false to let Bubbl. Nil
+    /// goes back to Bubbl showing everything. Called on the main thread.
+    public static func setNotificationListener(_ listener: (@MainActor @Sendable (BubblMessage) -> Bool)?) {
+        backend.setNotificationListener(listener)
+    }
+
+    /// Be told of what Bubbl does as it happens (`BubblEvent`), on the main thread. Keep the token
+    /// to remove the listener with.
+    @discardableResult
+    public static func addEventListener(_ listener: @escaping @MainActor @Sendable (BubblEvent) -> Void) -> BubblEventToken {
+        backend.addEventListener(listener)
+    }
+
+    public static func removeEventListener(_ token: BubblEventToken) {
+        backend.removeEventListener(token)
+    }
+
+    /// Show `message` in Bubbl's notification screen (one the listener held back, say).
+    public static func present(_ message: BubblMessage) {
+        backend.present(message)
+    }
+
+    /// For an app drawing notifications itself: it's on screen.
+    public static func reportDisplayed(_ message: BubblMessage) {
+        backend.report("reportDisplayed") { try await $0.displayed(message.notification) }
+    }
+
+    /// …the user opened it (tapped it, rather than it opening on its own).
+    public static func reportOpened(_ message: BubblMessage) {
+        backend.report("reportOpened") { try await $0.opened(message.notification) }
+    }
+
+    /// …the user tapped its call to action.
+    public static func reportCtaClicked(_ message: BubblMessage) {
+        backend.report("reportCtaClicked") { try await $0.ctaClicked(message.notification) }
+    }
+
+    /// …the user closed it without acting.
+    public static func reportDismissed(_ message: BubblMessage) {
+        backend.report("reportDismissed") { try await $0.dismissed(message.notification) }
+    }
+
+    /// …its media (video, audio, a YouTube video, an image) was shown or started playing.
+    public static func reportMediaViewed(_ message: BubblMessage) {
+        backend.report("reportMediaViewed") { try await $0.mediaViewed(message.notification, positionSeconds: 0) }
+    }
+
+    /// …its video or audio played to the end, `durationSeconds` long.
+    public static func reportMediaCompleted(_ message: BubblMessage, durationSeconds: Double) {
+        backend.report("reportMediaCompleted") { try await $0.mediaCompleted(message.notification, positionSeconds: durationSeconds) }
+    }
+
+    /// …the user started answering its survey.
+    public static func reportSurveyStarted(_ message: BubblMessage) {
+        backend.report("reportSurveyStarted") { try await $0.surveyStarted(message.notification) }
+    }
+
+    /// Send the answers to a survey the app showed itself: `answers` by question id, as each
+    /// `BubblQuestion` says. Checked as the server checks them; false (and a warning logged, with
+    /// why) when they can't be sent, e.g. a required question unanswered or a rating of 6.
+    @discardableResult
+    public static func submitSurvey(_ message: BubblMessage, answers: [String: Any?]) -> Bool {
+        backend.submitSurvey(message, answers: answers)
+    }
+
+    /// Open `message`'s call to action as Bubbl's screen would, and report the click.
+    public static func openCta(_ message: BubblMessage) {
+        backend.openCta(message)
+    }
+
+    // MARK: - Push
+
+    /// Whether a push is Bubbl's (its payload's `userInfo`), so the app's own handling can leave it
+    /// alone.
+    public static func isBubblMessage(_ userInfo: [AnyHashable: Any]) -> Bool {
+        backend.isBubblMessage(userInfo)
+    }
+
+    #if os(iOS)
+    // Bubbl takes the device token and its own pushes by itself. With BubblAutoIntegrationEnabled
+    // set to NO in Info.plist it doesn't, and the app hands them over with these three.
+
+    /// The device token, from the app delegate's
+    /// `application(_:didRegisterForRemoteNotificationsWithDeviceToken:)`. Before `start` too.
+    public static func setPushToken(_ deviceToken: Data) {
+        backend.setPushToken(deviceToken)
+    }
+
+    /// From the notification center delegate's `userNotificationCenter(_:willPresent:…)`: true
+    /// when the push is Bubbl's, and Bubbl calls `completionHandler`; false when it isn't, and the
+    /// app's own code decides.
+    public static func willPresent(_ notification: UNNotification, completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) -> Bool {
+        backend.willPresent(notification, completionHandler: completionHandler)
+    }
+
+    /// From the notification center delegate's `userNotificationCenter(_:didReceive:…)`: true when
+    /// the tapped notification is Bubbl's, and Bubbl calls `completionHandler`; false when it
+    /// isn't.
+    public static func didReceive(_ response: UNNotificationResponse, completionHandler: @escaping () -> Void) -> Bool {
+        backend.didReceive(response, completionHandler: completionHandler)
+    }
+    #endif
+
+    // MARK: - Diagnostics
+
+    /// Where Bubbl stands on this device, for support and for an app's own debug screen. The same
+    /// fields as Android's, and iOS's own at the end.
+    public struct Diagnostics: Sendable, Equatable {
+        public let started: Bool
+        /// Bubbl works on this device (iOS 17 and later): `Bubbl.isSupported`.
+        public let supported: Bool
+        public let sdkVersion: String
+        /// False when the workspace requires a newer SDK.
+        public let sdkSupported: Bool
+        public let registered: Bool
+        /// The install id the engine keeps (how Dashboard › Active users finds this device); nil
+        /// before there is one.
+        public let installId: String?
+        /// Running: started, consent allows it, not paused by the server, supported.
+        public let active: Bool
+        /// Unix seconds until which the server paused Bubbl, if it has.
+        public let pausedUntil: Int64?
+        public let consentRequired: Bool
+        public let consent: Bool?
+        public let locationEnabled: Bool
+        /// Where the device stands on the permissions Bubbl uses (as `permissions.status()`).
+        public let permissions: BubblPermissionStatus?
+        public let hasPushToken: Bool
+        public let geofences: Int
+        public let queuedEvents: Int
+        public let lastError: String?
+        /// Started with a credential the server refused (`Bubbl.start(credential:options:)`).
+        public let credentialRejected: Bool
+        /// Geofences work with the app closed ("Always"); else only while it's open.
+        public let backgroundLocation: Bool
+        /// Geofence entries and exits that happened before the first unlock after a reboot, when
+        /// they couldn't be kept (always 0 on Android).
+        public let transitionsDroppedWhileLocked: Int
+        /// iOS: Background App Refresh is on for the app.
+        public let backgroundRefreshAvailable: Bool
+        /// iOS: Low Power Mode is on (background work is held back).
+        public let lowPowerMode: Bool
+        /// iOS watches the geofences ("Always", precise, and the device can). Otherwise they're
+        /// checked from location changes, which is coarser.
+        public let osWatchesGeofences: Bool
+        /// The workspace the key belongs to: "sandbox" (pk_test_) or "production" (pk_live_); nil
+        /// before the device has registered (or from a server that predates Sandbox).
+        public let environment: String?
+        /// In Sandbox, where this device stands as a test device; nil in Production.
+        public let testDevice: TestDevice?
+
+        /// A Sandbox test device: "pending" until someone approves it (in the dashboard, with
+        /// `code`, or with `Bubbl.registerTestDevice`), then "approved". Unused for 30 days, or
+        /// removed in the dashboard, it's pending again.
+        public struct TestDevice: Sendable, Equatable {
+            public let status: String
+            /// While pending: the short code the dashboard lists this device under (e.g. K7Q-2MX).
+            public let code: String?
+        }
+    }
+
+    public static func diagnostics() async -> Diagnostics {
+        await backend.diagnostics()
+    }
+
+    /// `diagnostics()` for code that can't await; `completion` runs on the main thread.
+    public static func diagnostics(completion: @escaping @Sendable @MainActor (Diagnostics) -> Void) {
+        Task {
+            let result = await diagnostics()
+            await MainActor.run { completion(result) }
+        }
+    }
+
+    // MARK: - Internals
+
+    /// https only; http for local development (localhost, the Simulator's host, *.test).
+    static func isAllowedBaseUrl(_ url: String) -> Bool {
+        guard let components = URLComponents(string: url), let host = components.host?.lowercased(), !host.isEmpty else { return false }
+        switch components.scheme?.lowercased() {
+        case "https": return true
+        case "http": return host == "localhost" || host == "127.0.0.1" || host == "10.0.2.2" || host.hasSuffix(".test")
+        default: return false
+        }
+    }
+}

package/ios-sdk/BubblSDK/BubblBackend.swift

@@ -0,0 +1,118 @@
+import Foundation
+import os
+#if canImport(UserNotifications)
+import UserNotifications
+#endif
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// What `Bubbl`'s calls do: the engine on iOS 17 and later (`SupportedBubbl`), nothing below it
+/// (`UnsupportedBubbl`). Apps supporting older iOS versions can install Bubbl; it just does nothing
+/// on those phones. The engine and everything it uses are `@available(iOS 17, *)`, so the compiler
+/// proves that the one `#available` check in `Bubbl.backend` is the only way in.
+protocol BubblBackend: Sendable {
+    var isSupported: Bool { get }
+
+    func start(apiKey: String, options: BubblOptions)
+    func start(credential: BubblCredential, options: BubblOptions)
+    func stop()
+
+    func setConsent(_ granted: Bool)
+    func optOut()
+    func deleteMyData()
+    func setLocationEnabled(_ enabled: Bool)
+    func registerTestDevice(_ code: String) async -> BubblTestDeviceResult
+
+    func setSegments(_ segments: [String])
+    func track(_ name: String, properties: [String: Any?])
+
+    func setNotificationListener(_ listener: (@MainActor @Sendable (BubblMessage) -> Bool)?)
+    func addEventListener(_ listener: @escaping @MainActor @Sendable (BubblEvent) -> Void) -> BubblEventToken
+    func removeEventListener(_ token: BubblEventToken)
+    func present(_ message: BubblMessage)
+    func report(_ call: String, _ record: @escaping @Sendable (NotificationEvents) async throws -> Void)
+    func submitSurvey(_ message: BubblMessage, answers: [String: Any?]) -> Bool
+    func openCta(_ message: BubblMessage)
+
+    func isBubblMessage(_ userInfo: [AnyHashable: Any]) -> Bool
+    #if os(iOS)
+    func setPushToken(_ deviceToken: Data)
+    func willPresent(_ notification: UNNotification, completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) -> Bool
+    func didReceive(_ response: UNNotificationResponse, completionHandler: @escaping () -> Void) -> Bool
+    #endif
+
+    func permissionStatus() -> BubblPermissionStatus?
+    func requestPermission(_ request: PermissionRequest, _ call: String) async -> BubblPermissionStatus?
+    func openSettings()
+
+    func diagnostics() async -> Bubbl.Diagnostics
+}
+
+extension Bubbl {
+    /// The one way into the engine.
+    static let backend: any BubblBackend = {
+        if #available(iOS 17, *) { return SupportedBubbl() }
+        return UnsupportedBubbl()
+    }()
+}
+
+/// Below iOS 17: every call returns at once and does nothing. No install, no network, no prompts,
+/// no notification delegate, no background tasks, no location. `start` says so in the log, once
+/// per call; permission calls report nil (as before `start`) and never prompt; pushes and taps are
+/// left to the app.
+struct UnsupportedBubbl: BubblBackend {
+    var isSupported: Bool { false }
+
+    func start(apiKey: String, options: BubblOptions) { said(options) }
+    func start(credential: BubblCredential, options: BubblOptions) { said(options) }
+    func stop() {}
+
+    func setConsent(_ granted: Bool) {}
+    func optOut() {}
+    func deleteMyData() {}
+    func setLocationEnabled(_ enabled: Bool) {}
+    func registerTestDevice(_ code: String) async -> BubblTestDeviceResult {
+        BubblTestDeviceResult(approved: false, message: "Bubbl needs iOS 17 or later")
+    }
+
+    func setSegments(_ segments: [String]) {}
+    func track(_ name: String, properties: [String: Any?]) {}
+
+    func setNotificationListener(_ listener: (@MainActor @Sendable (BubblMessage) -> Bool)?) {}
+    func addEventListener(_ listener: @escaping @MainActor @Sendable (BubblEvent) -> Void) -> BubblEventToken {
+        BubblEventToken(id: UUID())
+    }
+    func removeEventListener(_ token: BubblEventToken) {}
+    func present(_ message: BubblMessage) {}
+    func report(_ call: String, _ record: @escaping @Sendable (NotificationEvents) async throws -> Void) {}
+    func submitSurvey(_ message: BubblMessage, answers: [String: Any?]) -> Bool { false }
+    func openCta(_ message: BubblMessage) {}
+
+    func isBubblMessage(_ userInfo: [AnyHashable: Any]) -> Bool { false }
+    #if os(iOS)
+    func setPushToken(_ deviceToken: Data) {}
+    func willPresent(_ notification: UNNotification, completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) -> Bool { false }
+    func didReceive(_ response: UNNotificationResponse, completionHandler: @escaping () -> Void) -> Bool { false }
+    #endif
+
+    func permissionStatus() -> BubblPermissionStatus? { nil }
+    func requestPermission(_ request: PermissionRequest, _ call: String) async -> BubblPermissionStatus? { nil }
+    func openSettings() {}
+
+    func diagnostics() async -> Bubbl.Diagnostics {
+        Bubbl.Diagnostics(
+            started: false, supported: false, sdkVersion: Bubbl.sdkVersion, sdkSupported: true, registered: false, installId: nil,
+            active: false, pausedUntil: nil, consentRequired: false, consent: nil, locationEnabled: true, permissions: nil,
+            hasPushToken: false, geofences: 0, queuedEvents: 0, lastError: nil, credentialRejected: false, backgroundLocation: false,
+            transitionsDroppedWhileLocked: 0, backgroundRefreshAvailable: false, lowPowerMode: ProcessInfo.processInfo.isLowPowerModeEnabled,
+            osWatchesGeofences: false, environment: nil, testDevice: nil
+        )
+    }
+
+    /// The one line `start` writes: os_log, since the SDK's own log (os.Logger) is iOS 14 and later.
+    private func said(_ options: BubblOptions) {
+        guard options.logLevel != .none else { return }
+        os_log("Bubbl %{public}@ needs iOS 17 or later: it does nothing on this device", log: OSLog(subsystem: "tech.bubbl.sdk", category: "Bubbl"), type: .info, Bubbl.sdkVersion)
+    }
+}

package/ios-sdk/BubblSDK/BubblCredential.swift

@@ -0,0 +1,30 @@
+import Foundation
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// A device credential issued outside the app (installs provisioned ahead of time, an app's own
+/// pairing flow), for `Bubbl.start(credential:options:)` instead of an API key. The same as
+/// Android's BubblCredential. Its secret is kept in the Keychain and never shown: not in
+/// `description`, not by `dump` or the debugger.
+public struct BubblCredential: Sendable, Equatable, CustomStringConvertible, CustomDebugStringConvertible, CustomReflectable {
+    public let keyId: String
+    public let secret: String
+    /// The install the credential was issued for (a pairing flow passes the install_id it paired
+    /// with).
+    public let installId: String
+
+    public init(keyId: String, secret: String, installId: String) {
+        self.keyId = keyId
+        self.secret = secret
+        self.installId = installId
+    }
+
+    public var description: String { "BubblCredential(keyId: \(keyId), installId: \(installId), secret: hidden)" }
+    public var debugDescription: String { description }
+    public var customMirror: Mirror {
+        Mirror(self, children: ["keyId": keyId, "installId": installId, "secret": "hidden"], displayStyle: .struct)
+    }
+
+    var issued: IssuedCredential { IssuedCredential(keyId: keyId, secret: secret, installId: installId) }
+}

package/ios-sdk/BubblSDK/BubblMessage.swift

@@ -0,0 +1,151 @@
+import Foundation
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// A notification from Bubbl, as an app's own handler sees it (`Bubbl.setNotificationListener`):
+/// enough to draw it itself, or to hand back to `Bubbl.present` to show Bubbl's screen. The same
+/// as Android's BubblMessage.
+public struct BubblMessage: Sendable, Hashable, CustomStringConvertible {
+    let notification: BubblNotification
+
+    init(_ notification: BubblNotification) {
+        self.notification = notification
+    }
+
+    /// A message back from its `json` (kept for an in-app inbox, say, then shown again with
+    /// `Bubbl.present`); nil when it isn't one.
+    public init?(json: String) {
+        guard let notification = BubblNotification(json: json) else { return nil }
+        self.init(notification)
+    }
+
+    /// Echo this on anything the app reports about it.
+    public var id: String { notification.campaignNotificationId }
+    public var headline: String { notification.headline }
+    public var body: String { notification.body }
+    public var isSurvey: Bool { notification.isSurvey }
+    /// From a Sandbox workspace: an app drawing it itself should mark it as such, as Bubbl's
+    /// screen does with its SANDBOX ribbon.
+    public var isSandbox: Bool { notification.sandbox }
+
+    /// image, video, audio, youtube, application, text or file; nil without media.
+    public var mediaType: String? { notification.media?.kind.rawValue }
+    public var mediaUrl: String? { notification.media?.url }
+    public var mediaThumbnailUrl: String? { notification.media?.pictureUrl }
+
+    public var ctaLabel: String? { notification.cta?.label }
+    public var ctaUrl: String? { notification.cta?.url }
+
+    /// A survey's questions in order (empty for a message), for an app drawing it itself.
+    public var questions: [BubblQuestion] { notification.questions.map(BubblQuestion.init) }
+
+    /// The whole notification as the device API sent it (JSON), e.g. to pass to a wrapper.
+    public var json: String { notification.jsonText }
+
+    public var description: String { "BubblMessage(\(id), \"\(headline)\")" }
+}
+
+/// One question of a survey, and what `Bubbl.submitSurvey` takes as its answer, by `type`:
+/// single choice a choice id; multiple choice a list of choice ids; rating a whole number 1–5;
+/// boolean true/false; number a number; slider a number from 0 to 10; open-ended text (≤ 2000).
+public struct BubblQuestion: Sendable, Hashable {
+    /// Android's BubblQuestion.Type (`Type` is taken in Swift).
+    public enum Kind: String, Sendable, CaseIterable {
+        case openEnded = "open_ended"
+        case singleChoice = "single_choice"
+        case multipleChoice = "multiple_choice"
+        case rating, boolean, number, slider
+    }
+
+    public struct Choice: Sendable, Hashable {
+        public let id: String
+        public let text: String
+    }
+
+    public let id: String
+    public let text: String
+    public let type: Kind
+    public let required: Bool
+    public let choices: [Choice]
+
+    init(_ question: BubblNotification.Question) {
+        id = question.id
+        text = question.text
+        type = Kind(rawValue: question.kind.rawValue) ?? .openEnded
+        required = question.required
+        choices = question.choices.map { Choice(id: $0.id, text: $0.text) }
+    }
+}
+
+/// What Bubbl does, as it happens, for an app that wants to know (`Bubbl.addEventListener`): each
+/// step of a notification's life, geofences entered and left, and errors. Delivered on the main
+/// thread. They're for the app's own use (its analytics, its UI); Bubbl records its own.
+///
+/// New cases arrive in minor versions, so switch over it with a `default:` branch.
+public enum BubblEvent: Sendable, Hashable {
+    /// A notification arrived (from a geofence, a push or a pull), before it's shown.
+    case notificationReceived(BubblMessage)
+    case notificationDisplayed(BubblMessage)
+    /// Opened from its system notification.
+    case notificationOpened(BubblMessage)
+    case notificationCtaClicked(BubblMessage)
+    case notificationDismissed(BubblMessage)
+    case mediaViewed(BubblMessage)
+    case mediaCompleted(BubblMessage)
+    case surveyStarted(BubblMessage)
+    case surveySubmitted(BubblMessage)
+    /// The device entered one of the workspace's locations.
+    case geofenceEntered(locationId: String)
+    case geofenceExited(locationId: String)
+    /// Something went wrong that Bubbl couldn't fix itself (also in diagnostics' lastError).
+    case error(message: String)
+    /// The server refused the credential Bubbl was started with (`Bubbl.start(credential:options:)`):
+    /// Bubbl has stopped until it's started with a new one.
+    case credentialRejected
+}
+
+/// What `Bubbl.addEventListener` returns, to remove that listener with (Swift closures have no
+/// identity to remove them by).
+public struct BubblEventToken: Hashable, Sendable {
+    let id: UUID
+}
+
+/// The app's event listeners, each told of every event on the main thread.
+final class BubblEvents: @unchecked Sendable {
+    static let shared = BubblEvents()
+
+    private let lock = NSLock()
+    private var listeners: [UUID: @MainActor @Sendable (BubblEvent) -> Void] = [:]
+
+    func add(_ listener: @escaping @MainActor @Sendable (BubblEvent) -> Void) -> BubblEventToken {
+        let id = UUID()
+        lock.sync { listeners[id] = listener }
+        return BubblEventToken(id: id)
+    }
+
+    func remove(_ token: BubblEventToken) {
+        lock.sync { _ = listeners.removeValue(forKey: token.id) }
+    }
+
+    func emit(_ event: BubblEvent) {
+        let current = lock.sync { Array(listeners.values) }
+        guard !current.isEmpty else { return }
+        Task { @MainActor in current.forEach { $0(event) } }
+    }
+
+    /// The event for a notification event the engine recorded (NotificationEvents' types).
+    static func event(_ type: String, _ message: BubblMessage) -> BubblEvent? {
+        switch type {
+        case "notification.displayed": .notificationDisplayed(message)
+        case "notification.opened": .notificationOpened(message)
+        case "notification.cta_clicked": .notificationCtaClicked(message)
+        case "notification.dismissed": .notificationDismissed(message)
+        case "media.viewed": .mediaViewed(message)
+        case "media.completed": .mediaCompleted(message)
+        case "notification.survey_started": .surveyStarted(message)
+        case "survey.submitted": .surveySubmitted(message)
+        default: nil
+        }
+    }
+}

package/ios-sdk/BubblSDK/BubblOptions.swift

@@ -0,0 +1,39 @@
+import Foundation
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// How `Bubbl.start` sets Bubbl up. The same options as Android's BubblOptions.
+public struct BubblOptions: Sendable, Equatable {
+    /// How much Bubbl writes to the system log (subsystem "tech.bubbl.sdk").
+    public enum LogLevel: String, Sendable, Equatable, CaseIterable, Codable {
+        case none, error, warning, info, debug
+
+        var core: LogSeverity? {
+            switch self {
+            case .none: nil
+            case .error: .error
+            case .warning: .warning
+            case .info: .info
+            case .debug: .debug
+            }
+        }
+    }
+
+    /// The Bubbl API to talk to (https). Required for now: 5.0 pre-releases have no default until
+    /// the production host is settled.
+    public var baseUrl: String
+    /// True when the app asks its users first: Bubbl does nothing (no network, no location, no
+    /// notifications) until `Bubbl.setConsent(true)`.
+    public var requireConsent: Bool
+    public var logLevel: LogLevel
+    /// The device's segments, as `Bubbl.setSegments` would set them.
+    public var segments: [String]?
+
+    public init(baseUrl: String, requireConsent: Bool = false, logLevel: LogLevel = .warning, segments: [String]? = nil) {
+        self.baseUrl = baseUrl
+        self.requireConsent = requireConsent
+        self.logLevel = logLevel
+        self.segments = segments
+    }
+}