CircleBox
DocumentationPricing
Sign InGet Started
Docs

Android Quickstart

Install CircleBox Android artifacts and wire crash context capture.

Install (GitHub Release AAR)

CircleBox Android is distributed via release artifacts today.

1) Download AARs from tagged release (v0.3.1)

  • circlebox-sdk-release.aar
  • circlebox-cloud-release.aar (optional)

2) Copy files into app module

  • <your-app>/app/libs/circlebox-sdk-release.aar
  • <your-app>/app/libs/circlebox-cloud-release.aar (optional)

3) Add repository in settings.gradle

text
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    flatDir {
      dirs("$rootDir/app/libs")
    }
  }
}

4) Add dependencies in app/build.gradle

text
dependencies {
  implementation(name: "circlebox-sdk-release", ext: "aar")
  implementation(name: "circlebox-cloud-release", ext: "aar") // optional
}

5) Add cloud permissions (only if using cloud uploader)

In app/src/main/AndroidManifest.xml:

text
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

6) Verify dependency wiring

text
./gradlew :app:assembleDebug

Verify checksums against the release checksums.txt.

Core Setup

Initialize once at startup.

Recommended: custom Application

text
import android.app.Application
import com.circlebox.sdk.CircleBox

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

AndroidManifest.xml:

text
<application
    android:name=".MyApp"
    ... >
</application>

Fallback: first activity

If you do not control Application, call CircleBox.start() in your launcher activity onCreate.

Then use APIs anywhere in app code:

text
CircleBox.breadcrumb("checkout_started", mapOf("flow" to "standard"))

Pending Crash Export

text
if (CircleBox.hasPendingCrashReport()) {
  val files = CircleBox.exportLogs(
    setOf(
      CircleBoxExportFormat.JSON,
      CircleBoxExportFormat.CSV,
      CircleBoxExportFormat.JSON_GZIP,
      CircleBoxExportFormat.SUMMARY
    )
  )
  println(files)
}

Optional Cloud Upload

Start cloud companion from the same startup location, right after CircleBox.start():

text
CircleBoxCloud.start(
  CircleBoxCloudConfig(
    endpoint = "https://circlebox.seunjeremiah.workers.dev",
    ingestKey = "paste_ingest_key_from_control_plane",
    flushIntervalSec = 15,
    immediateFlushOnHighSignal = true,
  )
)

Key rules:

  • ingestKey must be cb_live_*
  • usageBeaconKey must be cb_usage_* when usage beacon is enabled
Previous← iOS Quickstart NextFlutter Quickstart →