B Bubbl Docs

Location and Geofences

Bubbl uses location to evaluate campaigns that should appear near a place. Your app controls when to request location permissions and whether background location is appropriate.

Permission guidance

Ask for location permission only when the user understands why your app needs it.

Minimum permissions:

  • Foreground location for location-aware experiences while the app is open.
  • Background location only when your app needs geofence behavior while it is not visible.

On iOS, background location requires the right Background Modes capability and user permission. On Android, background location has a separate permission flow.

Enable SDK-managed location tracking

Set enableLocationTracking to true when booting if you want the SDK to manage tracking:

BubblConfig(
    apiKey = "<YOUR_BUBBL_API_KEY>",
    enableLocationTracking = true
)

You can also start and stop tracking after boot:

BubblSdk.startLocationTracking()
BubblSdk.stopLocationTracking()

Equivalent wrapper methods are available in Flutter and React Native.

Forward app-managed locations

If your app already manages location, forward updates to Bubbl:

BubblSdk.handleLocationUpdate(
    BubblLocation(latitude = 51.5074, longitude = -0.1278)
)

Flutter:

await BubblSdk.instance.handleLocationUpdate(
  const BubblLocation(latitude: 51.5074, longitude: -0.1278),
);

React Native:

await Bubbl.handleLocationUpdate({
  latitude: 51.5074,
  longitude: -0.1278,
});

Refresh geofences

Use refreshGeofence when you want the SDK to fetch and evaluate geofence campaign state for a known location:

BubblSdk.refreshGeofence(
    BubblLocation(latitude = 51.5074, longitude = -0.1278)
)

Use SDK events, diagnostics, and device logs to confirm the result. During smoke testing, watch for geofence snapshot, enter, exit, notification, or error events in the SDK event stream where your platform exposes events.

Retriggers

Campaign retrigger behavior is controlled by campaign settings in Bubbl. If a campaign does not trigger again during testing, check campaign cooldowns, maximum trigger settings, segment targeting, and device permission state.

Platform limits

Android and iOS may throttle background work to protect battery life.

iOS also limits the number of monitored regions and will usually not relaunch an app for background location after the user force-quits it.