Limitations

We would rather you know the gaps up front than discover them after buying.

Android only

There is no native iOS counterpart to this package yet. If you need both platforms from one codebase today, the React Native and Flutter SDKs wrap the same engine on iOS and Android.

Play Services required

Tracking is built on the fused location provider and Play Services activity recognition. Devices without Google Play Services — some China-market ROMs, plain AOSP builds — are not supported, and the SDK will not fall back to LocationManager.

Accepted-but-no-op config keys

Accepted for API compatibility with the other BGeo SDKs, currently doing nothing on Android:

Key	Status
foregroundService	No-op — the foreground service is always on while tracking, because Android requires it for background location.
backgroundPermissionRationale	No-op — the SDK uses Android’s own shouldShowRequestPermissionRationale flow rather than a config-driven dialog.
debug	Not a no-op, but plays audible sound cues only (location, heartbeat, motion change, stop timeout, geofence events). It changes nothing about tracking, filtering or upload.

iOS-only keys, stored but unread

These are part of the shared Config shape and are ignored here: showsBackgroundLocationIndicator, stationaryDistanceFilter, preventSuspend, useSessionEngine. You can leave them set — a config shared with an iOS build stays valid.

Behaviour worth knowing before you ship

Geofence transitions fire past the boundary. That is OS behaviour, not a bug: Android adds up to ~30 s of reporting latency (notificationResponsiveness) on top of fused-location detection lag, to keep GPS noise from flapping the region. The location attached to a geofence event is the last accepted fix at the moment the OS delivered the transition, so on a map the event marker lands where the device was when the OS decided, not on the circle’s edge. Size radii with that in mind — a 50 m geofence in a car is mostly a coin flip.

Doze and app standby throttle everything. With the screen off and the device stationary, Android batches location delivery and defers alarms. The engine’s stationary geofence and activity-recognition wakes are designed for this, but the first fix after a long Doze can be minutes late. This is the same constraint every background-location app on Android lives under.

Manufacturer battery managers can kill the service outright. Xiaomi, Huawei, Oppo, Vivo, OnePlus and Samsung ship aggressive process killers that ignore the foreground-service contract. The engine restarts with START_STICKY and re-arms on boot, but on those devices a user may need to whitelist your app in the vendor’s battery settings before background tracking is reliable. dontkillmyapp.com documents the per-vendor steps.

A killed process resumes at the next system event, not instantly. If the user force-stops your app from Settings, Android blocks every restart path until the app is launched again — no broadcast, no geofence, no alarm reaches it. This is by design in Android and cannot be worked around.

Deliberately out of scope

A large part of the Transistorsoft API is not here and is not planned: schedule/startSchedule, location/geofence templates, getLocations() pagination and SQL queries, startBackgroundTask/stopBackgroundTask, getDeviceInfo/getSensors, emailLog, reset(), startGeofences() geofence-only mode, and persistMode/timestampFormat/ locationsOrderDirection. The Methods reference is the complete list of what exists.