Bubbl Android SDK - Developer Reference and Integration Guide

🚀 Introduction

The Bubbl Android SDK provides low-latency geofence monitoring and campaign delivery using Android's background location services. It enables location-triggered engagement and supports Firebase Cloud Messaging (FCM) for push notifications.

Core Features

• Geofence enter/exit monitoring
• Segmentation and FCM support
• Kotlin Flows & LiveData support
• Fine-grained runtime permission support
• Lightweight footprint

Use Cases

• Retail engagement
• Event-based interactions
• Travel and routine-based triggers
• Real-world user journey analytics

---

✅ Getting Started

Requirements

Component	Version
Android Studio	Giraffe (AGP 8.1) or newer
Min SDK	23
Target SDK	34
Kotlin	1.6+
Google Play Services	Maps & Location
Firebase Messaging	FCM
Permissions	Location, Internet, Foreground Service, Notifications
google-services.json	Required in /app directory

---

1. SDK Integration

Gradle Setup

:::tabs

@tab Kotlin (KTS)

settings.gradle.kts

Kotlin

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
    maven {
      url = uri("https://maven.bubbl.tech/releases")
      credentials {
        username = "YOUR_USERNAME"
        password = "YOUR_API_TOKEN"
      }
    }
  }
}

app/build.gradle.kts

Kotlin

dependencies {
  implementation("tech.bubbl:sdk-android:2.0.3")
  implementation("com.google.android.gms:play-services-location:21.2.0")
  implementation("com.google.android.gms:play-services-maps:19.1.0")
  implementation("com.google.firebase:firebase-messaging-ktx:24.0.0")
  implementation("androidx.core:core-ktx:1.13.1")
  implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.1")
}

@tab Groovy

settings.gradle

Groovy

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven {
      url "https://maven.bubbl.tech/releases"
      credentials {
        username = "YOUR_USERNAME"
        password = "YOUR_API_TOKEN"
      }
    }
  }
}

app/build.gradle

Groovy

dependencies {
  implementation "tech.bubbl:sdk-android:2.0.3"
  implementation "com.google.android.gms:play-services-location:21.2.0"
  implementation "com.google.android.gms:play-services-maps:19.1.0"
  implementation "com.google.firebase:firebase-messaging-ktx:24.0.0"
}

:::

ℹ️

You can also use JitPack, GitHub Packages, or a local .aar file if preferred.

---

Manual .aar Integration

1. Download the .aar file
2. Add it to app/libs/
3. Update build.gradle:

Kotlin

repositories { flatDir { dirs("libs") } }
dependencies { implementation(files("libs/bubbl-sdk-2.0.3.aar")) }

Groovy:

Groovy

implementation(name: "bubbl-sdk-2.0.3", ext: "aar")

---

Version Catalog (Optional)

libs.versions.toml

TOML

[versions]
bubbl-sdk = "2.0.3"

[libraries]
bubbl-sdk = { group = "tech.bubbl", name = "sdk-android", version.ref = "bubbl-sdk" }

Usage in build.gradle.kts

Kotlin

implementation(libs.bubbl.sdk)

---

2. AndroidManifest Setup

Add required permissions and services:

XML

<manifest ...>

  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.INTERNET" />

  <application ...>

    <service
      android:name="tech.bubbl.sdk.services.LocationUpdatesService"
      android:foregroundServiceType="location" />

    <service
      android:name="tech.bubbl.sdk.services.MyFirebaseMessagingService"
      android:exported="true">
      <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
      </intent-filter>
    </service>

    <meta-data
      android:name="com.google.android.geo.API_KEY"
      android:value="YOUR_GOOGLE_MAPS_API_KEY" />

  </application>

</manifest>

⚠️

Ensure permissions are also requested at runtime for Android 10+ and API 33+ (e.g. notifications).

---

3. Initialization & Lifecycle

Application-level Initialization

Kotlin

class MyApp : Application() {
  override fun onCreate() {
    super.onCreate()

    FirebaseApp.initializeApp(this)

    BubblSdk.init(
      application = this,
      config = BubblConfig(
        apiKey = "YOUR_API_KEY",
        environment = Environment.STAGING,
        segmentationTags = listOf("example-tag"),
        geoPollInterval = 300_000L,
        defaultDistance = 25
      )
    )
  }
}

---

Activity-level Initialization (Alternative)

Kotlin

class MainActivity : ComponentActivity() {
  fun startBubbl() {
    BubblSdk.init(...)
    BubblSdk.startLocationTracking(this)
  }
}

---

4. Public API Reference

Kotlin

// Initialization
BubblSdk.init(application, config)
BubblSdk.registerDevice()

// Permissions
BubblSdk.requiredPermissions(): Array<String>
BubblSdk.locationGranted(): Boolean
BubblSdk.notificationGranted(): Boolean

// Lifecycle
BubblSdk.startLocationTracking(context)
BubblSdk.stopLocationTracking()

// Geofence
BubblSdk.refreshGeofence(lat, lng)
val flow = BubblSdk.geofenceFlow

---

Key Data Types

Kotlin

data class GeofenceSnapshot(
  polygons: List<PolygonData>,
  stats: GeofenceStats,
  campaignId: String?
)

enum class Environment {
  STAGING, PRODUCTION
}

data class BubblConfig(
  apiKey: String,
  environment: Environment,
  segmentationTags: List<String>,
  geoPollInterval: Long,
  defaultDistance: Int
)

---

PermissionManager Example

Kotlin

val permissionManager = PermissionManager(this)
val launcher = permissionManager.registerLauncher { granted ->
  if (granted) startBubbl()
}
launcher.launch(permissionManager.requiredPermissions())

---

✅ What’s Next?

• Hook into geofenceFlow to draw regions or trigger events
• Register devices for push campaigns
• Use PermissionManager for runtime UX
• Track and optimize campaign triggers in your analytics

---

Let me know if you’d like this exported as a .md file or added to a ReadMe API spec directly.