iOS Developer Documentation

Versions

Bubbl iOS Plugin Version: 2.0.7
Minimum iOS Version: 15.0
Xcode Version: 14.0+
Swift Version: 5.7+

Prerequisites

• A Bubbl Dashboard account with an active API key
• Firebase project with Cloud Messaging enabled
• Firebase Messaging SDK integrated - Required for FCM token generation
• Apple Developer account with push notification capability
• CocoaPods or manual framework integration setup

Integration Options

You can integrate the Bubbl iOS SDK using two methods. Note: These options are only for the Bubbl SDK itself—you can integrate Firebase using any method you prefer (CocoaPods, SPM, or manual).

• CocoaPods Integration - Recommended for automatic Bubbl SDK dependency management
• Manual Integration - Direct Bubbl framework integration

Bubbl API Key

To integrate the plugin with your app, you will need a unique

API Key

You will find your API_KEY on the Bubbl Dashboard Company page.

Key Features

• Geofence-based notifications: Trigger notifications when users enter/exit defined locations
• Firebase Cloud Messaging: Uses FCM tokens for reliable push notification delivery (Firebase Messaging required)
• Background monitoring: Continuous location tracking even when app is closed
• Segmentation support: Target specific user groups with custom tags
• Battery optimization: Efficient power management for location services

Required Permissions

Your app must request the following permissions:

• Location (Always): For background geofence monitoring
• Push Notifications: For notification delivery
• Background Modes: Location updates capability

SDK Architecture

The Bubbl iOS SDK consists of:

• BubblPlugin

  - Main SDK interface and initialization

• NotificationManager

  - Handles notification presentation and taps

• GeofenceService

  - Manages location-based triggers

• APIService

  - Backend communication (internal)

Quick Start Guide

1. Install the SDK via CocoaPods or manual integration
2. Install Firebase Messaging SDK (required dependency)
3. Configure Firebase and add

   GoogleService-Info.plist

4. Set up Firebase Messaging delegate to receive FCM tokens
5. Use gated initialization pattern to ensure FCM token is available before SDK start
6. Implement delegate callbacks for authentication status
7. Handle notification taps using NotificationManager

Messaging.messaging().token

Multi-SDK Notification Router Pattern

For apps using multiple notification SDKs, implement the notification router pattern where your host app owns the

UNUserNotificationCenter

Bubbl Notification Identification Fields

Bubbl notifications can be identified by these payload fields:

• n_id

  - Bubbl notification ID

• location_id

  - Bubbl location ID

• notification_data

  - Nested object containing Bubbl-specific data

Notification Router Implementation

Create a notification router class that your app owns:

import UserNotifications
import Bubbl

class AppNotificationRouter: NSObject, UNUserNotificationCenterDelegate {

    static let shared = AppNotificationRouter()

    func setup() {
        UNUserNotificationCenter.current().delegate = self
    }

    // MARK: - Check if notification is from Bubbl
    private func isBubblNotification(_ userInfo: [AnyHashable: Any]) -> Bool {
        // Check for Bubbl-specific fields
        if userInfo["n_id"] != nil { return true }
        if userInfo["location_id"] != nil { return true }
        if userInfo["notification_data"] != nil { return true }
        return false
    }

    // MARK: - Foreground presentation
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification,
        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
    ) {
        let userInfo = notification.request.content.userInfo

        if isBubblNotification(userInfo) {
            // Route to Bubbl SDK
            Bubbl.NotificationManager.shared.userNotificationCenter(
                center,
                willPresent: notification,
                withCompletionHandler: completionHandler
            )
        } else {
            // Handle other SDK notifications or your own
            // e.g., forward to Firebase, OneSignal, etc.
            completionHandler([.banner, .sound, .badge])
        }
    }

    // MARK: - Notification tap handling
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
    ) {
        let userInfo = response.notification.request.content.userInfo

        if isBubblNotification(userInfo) {
            // Route to Bubbl SDK
            Bubbl.NotificationManager.shared.userNotificationCenter(
                center,
                didReceive: response,
                withCompletionHandler: completionHandler
            )
        } else {
            // Handle other SDK notifications or your own
            completionHandler()
        }
    }
}

Setup in AppDelegate

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {

    // Configure Firebase first
    FirebaseApp.configure()

    // Set YOUR app as the notification delegate (not Bubbl SDK)
    AppNotificationRouter.shared.setup()

    // Request permissions
    UNUserNotificationCenter.current().requestAuthorization(
        options: [.alert, .sound, .badge]
    ) { granted, _ in
        DispatchQueue.main.async {
            application.registerForRemoteNotifications()
        }
    }

    return true
}

Delegate Verification Pattern

After starting the Bubbl SDK, verify that your delegate wasn't overridden. Some SDKs may set the delegate asynchronously during initialization:

// After calling BubblPlugin.shared.start(...)
DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
    let currentDelegate = UNUserNotificationCenter.current().delegate

    if currentDelegate === AppNotificationRouter.shared {
        print("✅ Delegate still set correctly after SDK start")
    } else {
        print("⚠️ Delegate was overridden - resetting...")
        AppNotificationRouter.shared.setup()
    }
}

Support and Documentation

For detailed implementation guides, please refer to:

• CocoaPods Integration Guide
• Manual Integration Guide
• Firebase Configuration

Respecting your app users

The Bubbl Plugin can be configured to respect app users by restricting notification features when a device’s battery reaches a lower limit; this can be set on the SDK Configurations page.