Example app

The SDK repository ships a full console under example/. It is not a hello-world: it is the tool the SDK is developed against, and the fastest way to see what a config change actually does on a real device.

git clone https://github.com/dc-bgeo/android-background-geolocation.git
cd android-background-geolocation
./gradlew :example:assembleDebug

It builds unlicensed — debuggable builds run in evaluation mode — so there is nothing to buy before trying it.

Three tabs

Map — the live track, geofence circles and pins, and the controls that matter while walking around with a phone: Start/Stop, a one-shot Get position, layer toggles (Follow, points, polyline, geofences), and a from/to range picker that reloads history from the web console when the device is linked. Long-press the map to create a geofence; tap a pin to edit or delete it. Long tracks are drawn a page at a time, newest first, with a pager for stepping back.

The Android example app's Map tab: a live track drawn as a blue polyline with breadcrumb dots, a geofence drawn as an orange circle, the status row showing link state, motion state, battery and point count, and the control card with Stop, Get position, layer toggles and the from/to range picker.

Logs — the merged event stream: your app’s lines and the engine’s own diagnostics on one timeline, filtered by level, with follow-tail and clear. This is the same data getLog() returns, which makes it a good way to learn what the engine logs before you go looking for it in the field.

Settings — every working config key, grouped, applied immediately through setConfig() and persisted as overrides. Rejected values surface their error next to the field that failed rather than in a toast. Below the config there is an engine panel: the getState() health fields, the upload-queue and log counters, and the actions that have no other home — sync(), destroy queue, upload/destroy log, changePace(), resetOdometer().

The Android example app's Settings tab: the debug-console link form, the authorization-request selector, and the geolocation config keys with inline controls.

The engine panel at the bottom of the Settings tab: getState() health fields (enabled, trackingActive, isMoving, odometer, geofenceCount, authorization, fix ages, tracking mode, connectivity), the upload-queue and log-history counters, and the action buttons.

The engine panel, below the config keys.

Linking it to the web console

The example can stream to the BGeo web console, which is worth doing even for local development: it is far easier to reason about a track on a large map than in logcat.

Create a registration code in the console (Dashboard → Registration codes), enter it in the example’s Settings tab, and locations and logs start arriving. Everything after the code exchange is native — the device keeps uploading with the app closed.

What to read in it

The example mirrors the React Native and Flutter examples file for file, so a concept you find here has a counterpart there. The parts worth reading if you are integrating:

File	Why
`ExampleApplication.kt`	`attach()` in `Application.onCreate`, and why it is there and not in the Activity.
`ExampleApp.kt`	Event subscriptions and `ready()` in the order that matters — subscribe first, then restore the device link, then `ready()`.
`MainActivity.kt`	`PermissionRequester` constructed in `onCreate`, before the Activity starts.
`ConfigSchema.kt`	Every config key with its real default — the same table as the Config reference, in code.
`DeviceLink.kt`	A complete JWT setup: registration, `authorization` config, and native token refresh.

Its own tests

./gradlew :example:test

The example’s non-UI logic — the config store, the device link, the history loader, the log pipeline — is unit-tested on the JVM. Worth a look if you want a model for testing your own integration without an emulator in the loop.