ChangelogEdit pageSTAFFOpen dashboard
GuidesAdding Bubbl to an existing app

Adding Bubbl to an existing app

Bubbl works beside your own Firebase service, notification delegate, permission flow and startup setup. What to keep, and the few things not to remove.

Bubbl is built to sit beside what your app already has. None of the usual integrations need changing, and none of Bubbl's setup needs code beyond start.

Where to start Bubbl#

Start Bubbl early, at every launch, so background launches for a geofence or a push have it:

  • Android: in Application.onCreate. If your app has no Application class yet, add one and register it with android:name in AndroidManifest.xml. Not in an activity: only Application.onCreate runs when Android wakes your app in the background.
  • iOS: in your SwiftUI App's init, or in application(_:didFinishLaunchingWithOptions:).
  • Flutter: in main(), after WidgetsFlutterBinding.ensureInitialized() and before runApp.
  • React Native: at the top of index.js; with Expo Router, at the top of app/_layout.tsx, outside the component.

Starting again with the same key and options changes nothing, so it's safe to call on every launch.

Push#

  • Your own FirebaseMessagingService, firebase_messaging or React Native Firebase: keep it. Bubbl receives its pushes beside it and needs no forwarded tokens or payloads. Bubbl's pushes also reach your handler, so skip them with Bubbl.isBubblMessage(data). Your app's Firebase project must be the one whose service account is in the dashboard. See Push notifications.
  • Your own UNUserNotificationCenter delegate, Firebase, or plugins such as flutter_local_notifications: nothing to change. Bubbl extends whichever delegate is set and answers only for its own pushes. To hand pushes over yourself instead, set BubblAutoIntegrationEnabled to NO in Info.plist. See Push notifications.
  • Your own notification service extension: override didReceive(_:withContentHandler:) and call super only when BubblNotificationService.isBubbl(request) is true. See Pictures on iOS pushes.

Permissions and location#

  • Your own permission flow (your own prompts, or a library such as permission_handler): you don't have to use Bubbl.permissions. Bubbl uses whatever the user allowed. On Android, if you ask for background location yourself, show Google Play's prominent disclosure yourself too.
  • Your own geofences on iOS: iOS allows 20 monitored regions per app, shared by your app and every SDK in it. Bubbl takes what's left, up to 19 plus one refresh region, and takes fewer when iOS says the app is over. Its regions are named bubbl.…, so you can tell them apart.
  • Your own geofences on Android: Google Play services allows 100 geofences per app, shared with yours. Bubbl uses at most 51.

Your own notification UI#

To show Bubbl's notifications in your own design, set a notification listener and report what happens. See Drawing notifications yourself.

AndroidX App Startup#

Bubbl registers an AndroidX App Startup initializer, tech.bubbl.sdk.engine.BubblInitializer, through the SDK's manifest. Don't remove androidx.startup.InitializationProvider from your manifest with tools:node="remove". To turn off another library's initializer, remove only that library's <meta-data> entry and keep Bubbl's.

Without Bubbl's initializer, nothing reports an error, but app opens aren't noticed: no missed pushes are fetched when the app comes to the front, and geofences aren't checked while the app is open without background location. A push that starts a closed app also can't start the dashboard's Firebase, and Bubbl.permissions.openSettings() does nothing before start.

R8 and ProGuard#

No rules to add. The SDK needs no keep rules of its own.

Flutter's Kotlin Gradle plugin#

The plugin applies the Kotlin Gradle plugin only when your app has no Kotlin of its own. With Android Gradle Plugin 9's built-in Kotlin, or the plugin Flutter 3.44 and later applies, it uses that, so newer Flutter doesn't warn about plugins applying it.

Minimum versions#

You don't need to raise your app's minimums: the SDK installs from Android API 23 and iOS 13.0, and stays inactive on devices below Android 8.1 and iOS 17. See Requirements.

Events#

If you listen with addEventListener, give your when an else branch or your switch a default case: new event types arrive in minor releases. See Segments and events.

Coming from Bubbl 4.x#

5.0 is a clean break: a new API with no compatibility layer, and no 4.x data carries over, so each install registers as new. Remove the 4.x integration and follow Migrating from 4.x to 5.x.