ChangelogEdit pageSTAFFOpen dashboard
Get startedHow Bubbl works

How Bubbl works

What the SDK does in your app, what the Bubbl platform decides, and what your app still owns.

Bubbl has two halves. In the dashboard, your team draws locations, writes notifications and surveys, and builds campaigns that target them. In your app, the Bubbl SDK watches the geofences, receives pushes, shows notifications and surveys, and reports what happened. The two talk over Bubbl's device API at your workspace's API address.

What happens after start#

  1. Registration. On first launch the install registers with your SDK API key. The key only identifies your workspace, so it's safe to ship in the app. From then on the install signs its own requests with a credential of its own, kept in the Android Keystore or the iOS Keychain.
  2. Configuration. The SDK fetches its settings from the dashboard (for example the privacy view mode and text) and refreshes them now and then.
  3. Geofences. The server sends the geofences near the device and the SDK hands them to the OS to watch: up to 50 plus a refresh circle on Android, and up to 19 of the nearest plus a refresh region on iOS, which allows 20 per app shared with your own and other SDKs'. When the device moves on, the refresh area brings the next set.
  4. Transitions. Entering or leaving a geofence is sent to the server, retried if the network is down. The server decides whether a notification follows: cooldowns, trigger limits and quiet hours are the server's, set in the dashboard.
  5. Notifications. A notification arrives from a geofence, a push or a pull (missed pushes are fetched when the app comes to the front). With your app in front, Bubbl's notification screen opens straight away; otherwise it's a system notification whose tap opens the screen. Each notification shows once per install, however it arrives.
  6. Events. What the user does (displayed, opened, the call to action, media, survey answers) goes into a queue on the device and is sent in batches, so it survives being offline. Your app can listen to the same events.

All of this keeps working when the OS wakes your app in the background for a geofence or a push. On Android that's why start belongs in Application.onCreate. In Flutter and React Native apps the native SDK starts itself from its saved settings, before any Dart or JavaScript runs.

What Bubbl handles, and what your app owns#

Bubbl handles:

  • registering the install, signing requests and keeping its credential;
  • geofence watching and the background work around it, including after a reboot or an app update;
  • receiving pushes (Android through your Firebase project, iOS straight from Apple) and drawing Bubbl's notifications;
  • the notification screen: text, media, the call to action and the survey wizard;
  • the event queue and analytics.

Your app owns:

  • calling start early at every launch;
  • when to ask for permissions, and whether to use Bubbl's privacy view or your own explanation;
  • consent, if your users must agree first (requireConsent);
  • your platform setup: the Info.plist strings and push capability on iOS, the Play Console location declaration on Android, and the push credentials in the dashboard.

Everything else is optional: segments for targeting, custom events, listening to events, and drawing notifications in your own UI.

Sandbox and Production#

Every Bubbl company has a free Sandbox workspace and a paid Production workspace, each with its own key and API address. You develop against the Sandbox, where only the test phones you approve get anything, and ship with the Production key. See Sandbox and Production.

Older devices#

The SDK installs on Android from API 23 and iOS from 13.0, so it doesn't raise your app's minimums, but it only runs on Android 8.1 (API 27) and later and iOS 17 and later. On an older device start logs one line and does nothing else, every other call is a safe no-op, and listeners never fire. Bubbl.isSupported tells you ahead of time. See Requirements.

Next#