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

No account or key is needed, and everything the app records — track, logs, geofences — stays on the device. 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 filters the track recorded on the device. 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 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 app does not configure the SDK’s HTTP uploader (url, logUrl, authorization). To try uploads against your own endpoint, add those keys to baseConfig in Sources/BGeoExampleApp.swift — see the HTTP guide.

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 `ready()`.
`ConfigSchema.swift`	Every config key with its real default — the same table as the Config reference, in code.
`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 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.