iOS Quickstart

This page adds Bubbl to a native iOS app.

Requirements

• iOS 15 or newer.
• Swift 5.9 or newer.
• Push Notifications capability if you want push.
• Background Modes if you want background location or remote notification handling.
• Firebase configured if you use FCM.

Install with Swift Package Manager

Add the Bubbl SDK package in Xcode:

https://github.com/bubbl-platform/renewed-sdk

Choose the BubblSDK package product and version 4.0.2.

Install with CocoaPods

pod 'BubblSDK', '4.0.2'

Then run:

pod install

Boot the SDK

import BubblSDK

func bootBubbl() {
    Task {
        do {
            let result = try await BubblClient.shared.boot(
                BubblConfig(
                    apiKey: "<YOUR_BUBBL_API_KEY>",
                    environment: .production,
                    enablePushHandling: true,
                    enableLocationTracking: false
                )
            )

            print("Bubbl ready: \(result.ready)")
        } catch {
            print("Bubbl boot failed: \(error)")
        }
    }
}

Use .production for the live Bubbl environment.

Push token forwarding

Add the required permission text to Info.plist before requesting location:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app uses your location to show eligible Bubbl campaigns.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app uses background location to show eligible Bubbl campaigns near saved places.</string>

If you use background location, enable Background Modes > Location updates in Xcode.

Ask for notification permission and register for remote notifications:

UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in
    if granted {
        DispatchQueue.main.async {
            UIApplication.shared.registerForRemoteNotifications()
        }
    }
}

Forward the APNs token:

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    Task {
        try? await BubblClient.shared.updateAPNsToken(deviceToken)
    }
}

If your app uses Firebase Messaging, forward the FCM token:

Task {
    try? await BubblClient.shared.updateFCMToken(token)
}

When your app receives a remote notification payload, forward it:

Task {
    let bubblPayload = try? await BubblClient.shared.handleRemoteNotification(userInfo)
}

When the user taps a notification, forward the notification response:

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse
) async {
    _ = try? await BubblClient.shared.handleNotificationResponse(response)
}

iOS background behavior

iOS decides when an app can wake in the background. Location and remote notification handling require the correct capabilities, permissions, and user settings.

If a user force-quits the app, iOS generally will not relaunch it for background location or push processing until the user opens the app again.

First verification

Task {
    let diagnostics = await BubblClient.shared.diagnostics()
    print(diagnostics)
}

Expected signs of a healthy setup:

• SDK version is 4.0.2.
• The SDK reports booted after a successful boot.
• Push token suffix appears after a token has been registered.