Usage – Manual Only

func start(
  apiKey:        String,
  env:           Config.Environment       = .staging,     // .development | .staging | .production
  segmentations: [String]                 = [],           // audience tags (empty by default)
  delegate:      BubblPluginDelegate?     = nil
)

What it does: Boots every SDK subsystem—device registration, geofence polling, live GPS, push-routing, analytics.
When to call: Once, as early as possible (e.g. in AppDelegate.application(_:didFinishLaunchingWithOptions:)).

// AppDelegate.swift
import FirebaseCore
import Bubbl

func application(_ app: UIApplication,
                 didFinishLaunchingWithOptions opts: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  FirebaseApp.configure()  // Required for push notifications
  
  // IMPORTANT: Initialize Bubbl SDK only after receiving FCM token
  // See complete example in section 2.5 above
  
  return true
}

@objc public static func updateFCMToken(_ token: String)

What it does: Forwards FCM token to the SDK for Firebase Cloud Messaging.
When to call: In your FCM delegate when FCM token is received.

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    if let token = fcmToken {
        BubblPlugin.updateFCMToken(token)
    }
}

// Swift
public func updateSegments(
    segmentations: [String],
    completion: ((Result<Bool, Error>) -> Void)? = nil
)

// Objective-C
- (void)updateSegments:(NSArray *)segmentations
            completion:(void (^)(BOOL success, NSError *error))completion

What it does: Updates device segmentation tags after initialization. This allows you to dynamically change which campaigns/notifications the device receives based on user behavior or state changes.
When to call: After user login, subscription changes, preference updates, or any event that changes user segmentation.
Important: SDK must be initialized with start() before calling this method.

Swift Example:

// Update segments when user subscribes to premium
func userDidSubscribeToPremium() {
    BubblPlugin.shared.updateSegments(segmentations: ["premium", "subscribed"]) { result in
        switch result {
        case .success:
            print("✅ Segments updated successfully")
        case .failure(let error):
            print("❌ Failed to update segments: (error.localizedDescription)")
        }
    }
}

// Update segments based on user location region
func userDidChangeRegion(to region: String) {
    let newSegments = ["region_(region)", "active_user"]
    BubblPlugin.shared.updateSegments(segmentations: newSegments) { result in
        if case .success = result {
            print("User is now targeting region: (region)")
        }
    }
}

Objective-C Example:

// Update segments when user subscribes to premium
- (void)userDidSubscribeToPremium {
    NSArray *newSegments = @[@"premium", @"subscribed"];
    [BubblPlugin.shared updateSegments:newSegments completion:^(BOOL success, NSError *error) {
        if (success) {
            NSLog(@"✅ Segments updated successfully");
        } else {
            NSLog(@"❌ Failed to update segments: %@", error.localizedDescription);
        }
    }];
}

// Update segments based on user preferences
- (void)updateUserSegments {
    NSArray *segments = @[@"newsletter_subscriber", @"loyalty_member"];
    [BubblPlugin.shared updateSegments:segments completion:nil];  // No completion handler needed
}

Common Use Cases:

• User Authentication: Update segments when user logs in/out
• Subscription Changes: Premium, free, trial user segments
• Location/Region: Geographic targeting based on user location
• Preferences: Interest-based segments (sports, news, etc.)
• Behavior: Active users, power users, new users
• Demographics: Age groups, language preferences

func refetchGeofence()

What it does: Manually triggers a geofence fetch from the backend. This is useful for refreshing geofences on-demand without waiting for the automatic polling interval (5 minutes).

When to call:

• After location permission is granted
• When user enters a new region or city
• After segments are updated (to get relevant geofences)
• On app launch if geofences haven't loaded yet

Swift Example:

// Manually trigger geofence refresh
BubblPlugin.shared.refetchGeofence()

// Common use case: After location permission granted
func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
    if manager.authorizationStatus == .authorizedWhenInUse ||
       manager.authorizationStatus == .authorizedAlways {
        // Refresh geofences now that we have location permission
        BubblPlugin.shared.refetchGeofence()
    }
}

Objective-C Example:

// Manually trigger geofence refresh
[BubblPlugin.shared refetchGeofenceObjC];

// Common use case: After location permission granted
- (void)locationManagerDidChangeAuthorization:(CLLocationManager *)manager {
    CLAuthorizationStatus status = manager.authorizationStatus;
    if (status == kCLAuthorizationStatusAuthorizedWhenInUse ||
        status == kCLAuthorizationStatusAuthorizedAlways) {
        // Refresh geofences now that we have location permission
        [BubblPlugin.shared refetchGeofenceObjC];
    }
}

func getPrivacyText() -> String
func refreshPrivacyText(completion: ((Result<String, Error>) -> Void)?)

What they do:

• getPrivacyText() - Returns cached privacy text without network call
• refreshPrivacyText() - Fetches latest configuration from backend

When to use: Display privacy policy text in settings, consent screens, or onboarding flows. The text is configured in your Bubbl dashboard.

Swift Example:

// Get cached privacy text
let privacyText = BubblPlugin.shared.getPrivacyText()
print("Privacy: \(privacyText)")

// Refresh from backend
BubblPlugin.shared.refreshPrivacyText { result in
    switch result {
    case .success(let text):
        print("Updated privacy text: \(text)")
        // Update UI with new text
        self.privacyLabel.text = text
    case .failure(let error):
        print("Failed to refresh: \(error)")
    }
}

// Access full configuration (advanced)
if let config = BubblPlugin.shared.getCurrentConfiguration() {
    print("Notifications count: \(config.notificationsCount)")
    print("Days count: \(config.daysCount)")
    print("Battery count: \(config.batteryCount)")
    print("Privacy text: \(config.privacyText)")
}

Objective-C Example:

// Get cached privacy text
NSString *privacyText = [BubblPlugin.shared getPrivacyTextObjC];
NSLog(@"Privacy: %@", privacyText);

// Refresh from backend
[BubblPlugin.shared refreshPrivacyText:^(NSString *text, NSError *error) {
    if (error) {
        NSLog(@"Failed to refresh: %@", error);
    } else {
        NSLog(@"Updated privacy text: %@", text);
        // Update UI with new text
        self.privacyLabel.text = text;
    }
}];

// BubblPluginDelegate
func bubblPlugin(_ plugin: BubblPlugin,
                 didAuthenticate deviceID: String,
                 bubblID: String)

func bubblPlugin(_ plugin: BubblPlugin,
                 didFailWith error: Error)

What they do: Authentication callbacks when the SDK successfully registers the device or encounters an error. Use these for initialization confirmation and error handling.

Note: For geofence events, use the GeofenceService or ForegroundGeofenceMonitor classes which provide real-time location-based callbacks.

func requestLocationWhenInUse()

What it does: Requests location permission for when the app is in use.
When to call: When you need location access during app usage.

func requestLocationAlways()

What it does: Requests location permission for background location access.
When to call: When you need location access in the background for geofencing.

func requestPushPermission()

What it does: Requests push notification permission.
When to call: When you want to send push notifications to the user.

// Location updates you can observe
func locationManager(_ mgr: CLLocationManager,
                     didUpdateLocations locs: [CLLocation])

func locationManagerDidChangeAuthorization(_ mgr: CLLocationManager)

Why: If you want your ownCLLocationManager delegate tap-through without breaking Bubbl’s internal handling, forward these calls.

Some Public Methods

public var locationAuthorizationStatus: CLAuthorizationStatus

public var pushAuthorizationStatus: UNAuthorizationStatus

public var locationAuthorizationStatusRaw: Int

public var pushAuthorizationStatusRaw: Int

Usage Examples

Swift - Checking Permission Status:

// Check current location permission status
let locationStatus = BubblPlugin.shared.locationAuthorizationStatus
switch locationStatus {
case .notDetermined:
    print("Location permission not yet requested")
    BubblPlugin.shared.requestLocationWhenInUse()
case .denied, .restricted:
    print("Location permission denied - show settings alert")
case .authorizedWhenInUse:
    print("Location permission granted for when in use")
    // Request always permission for geofencing
    BubblPlugin.shared.requestLocationAlways()
case .authorizedAlways:
    print("Location permission granted for always - ready for geofencing")
@unknown default:
    print("Unknown location permission status")
}

// Check push notification permission status
let pushStatus = BubblPlugin.shared.pushAuthorizationStatus
switch pushStatus {
case .notDetermined:
    print("Push permission not yet requested")
    BubblPlugin.shared.requestPushPermission()
case .denied:
    print("Push permission denied - show settings alert")
case .authorized:
    print("Push notifications enabled")
case .provisional:
    print("Push notifications provisionally authorized")
@unknown default:
    print("Unknown push permission status")
}

Objective-C - Using Raw Integer Values:

// Check location permission using raw integer values (useful for KVC)
NSInteger locationStatusRaw = [BubblPlugin shared].locationAuthorizationStatusRaw;
if (locationStatusRaw == 0) {
    NSLog(@"Location permission not determined");
} else if (locationStatusRaw == 1 || locationStatusRaw == 2) {
    NSLog(@"Location permission denied or restricted");
} else if (locationStatusRaw == 3) {
    NSLog(@"Location authorized when in use");
} else if (locationStatusRaw == 4) {
    NSLog(@"Location authorized always - ready for geofencing");
}

// Check push permission using raw integer values
NSInteger pushStatusRaw = [BubblPlugin shared].pushAuthorizationStatusRaw;
if (pushStatusRaw == 0) {
    NSLog(@"Push permission not determined");
} else if (pushStatusRaw == 1) {
    NSLog(@"Push permission denied");
} else if (pushStatusRaw == 2) {
    NSLog(@"Push notifications authorized");
}

SwiftUI - Reactive Updates:

import SwiftUI
import Combine
import Bubbl

struct PermissionStatusView: View {
    @State private var locationStatus: CLAuthorizationStatus = .notDetermined
    @State private var pushStatus: UNAuthorizationStatus = .notDetermined
    private var cancellables = Set<AnyCancellable>()
    
    var body: some View {
        VStack(spacing: 16) {
            // Location Status
            HStack {
                Text("Location:")
                Spacer()
                Text(locationStatusText)
                    .foregroundColor(locationStatusColor)
            }
            
            // Push Status
            HStack {
                Text("Push Notifications:")
                Spacer()
                Text(pushStatusText)
                    .foregroundColor(pushStatusColor)
            }
            
            // Action buttons
            if locationStatus != .authorizedAlways {
                Button("Request Location Permission") {
                    BubblPlugin.shared.requestLocationAlways()
                }
            }
            
            if pushStatus != .authorized {
                Button("Request Push Permission") {
                    BubblPlugin.shared.requestPushPermission()
                }
            }
        }
        .onAppear {
            updateStatus()
            setupStatusObservers()
        }
    }
    
    private func updateStatus() {
        locationStatus = BubblPlugin.shared.locationAuthorizationStatus
        pushStatus = BubblPlugin.shared.pushAuthorizationStatus
    }
    
    private func setupStatusObservers() {
        // Subscribe to permission changes
        BubblPlugin.locationAuthorizationPublisher
            .sink { status in
                locationStatus = status
            }
            .store(in: &cancellables)
            
        BubblPlugin.pushAuthorizationPublisher
            .sink { status in
                pushStatus = status
            }
            .store(in: &cancellables)
    }
    
    private var locationStatusText: String {
        switch locationStatus {
        case .notDetermined: return "Not Asked"
        case .denied, .restricted: return "Denied"
        case .authorizedWhenInUse: return "When In Use"
        case .authorizedAlways: return "Always"
        @unknown default: return "Unknown"
        }
    }
    
    private var pushStatusText: String {
        switch pushStatus {
        case .notDetermined: return "Not Asked"
        case .denied: return "Denied"
        case .authorized: return "Authorized"
        case .provisional: return "Provisional"
        @unknown default: return "Unknown"
        }
    }
    
    private var locationStatusColor: Color {
        switch locationStatus {
        case .authorizedAlways: return .green
        case .authorizedWhenInUse: return .orange
        case .denied, .restricted: return .red
        default: return .gray
        }
    }
    
    private var pushStatusColor: Color {
        switch pushStatus {
        case .authorized: return .green
        case .denied: return .red
        default: return .gray
        }
    }
}