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/ios-background-geolocation.git
cd ios-background-geolocation/Example
xcodegen generate          # the .xcodeproj is generated, not committed
open BGeoExample.xcodeproj

It builds unlicensed — debug builds and the Simulator run in evaluation mode — so there is nothing to buy before trying it. Run it on a device for anything to do with background behaviour.

Three tabs

Map — the live track on MapKit, 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.

The iOS example app's Map tab: a live track drawn as a blue polyline with breadcrumb dots, a geofence circle labelled office around the destination, the status row showing link state, motion state and point count, and the control card with Stop, Get position and layer toggles.

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 an alert. 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(), requestTemporaryFullAccuracy().

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

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 a console log.

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
`BGeoExampleApp.swift`	Event subscriptions and `ready()` in the order that matters — subscribe first, then restore the device link, then `ready()`.
`ConfigSchema.swift`	Every config key with its real default — the same table as the Config reference, in code.
`DeviceLink.swift`	A complete JWT setup: registration, `authorization` config, and native token refresh.
`Screens/MapScreen.swift`	Drawing a live track without re-rendering it on every fix — the annotations are diffed and the current-position marker is moved, not replaced.

Its own tests

xcodebuild test -scheme BGeoExample -destination 'platform=iOS Simulator,name=iPhone 17'

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