Integrate the SDK

The AAR supplies its own services, receivers, permissions and consumer ProGuard rules through manifest merging. No Hilt, no DI framework, no annotation processor and no TrackIt Gradle plugin.

implementation 'com.github.devstree-prog.TrackIt:trackit-all:TAG'
implementation("com.squareup.okhttp3:okhttp:5.4.0")

compileSdk 37 is load-bearing

The AAR declares minCompileSdk=37, so AGP hard-errors below it. This needs a recent AGP - the default templates ship lower, so bump it in your host app.

Create the process singleton and prepare it once from Application.onCreate. ready() is a suspend function and returns TrackItResult<TrackItState>.

val trackIt = TrackIt.getInstance(applicationContext)

when (val result = trackIt.ready(TrackItConfig(accessKey = "TRACKIT-eyJ…"))) {
    is TrackItResult.Ok    -> Unit
    is TrackItResult.Error -> Log.e("TrackIt", "${result.code}: ${result.message}")
}

Calling start() before ready() returns NOT_READY. Both start() and stop() are suspend functions; this release ships no callback or Future facade.

Permissions, in order

1. Notification (API 33+)
2. Fine or coarse foreground location
3. Background location - a separate request, which Android will not grant in the same prompt
4. Activity recognition, if you want motion-triggered capture

Modes

• CONTINUOUS - a fix on a fixed interval. Predictable, heaviest on battery.
• ADAPTIVE - cadence follows speed and context. The sensible default.
• MOTION_ONLY - nothing until the device moves. Lightest, best for long idle periods.

Accuracy and providers

Profiles are STRICT (20m), BALANCED (30m) and RELAXED (60m). Providers are FUSED, GPS_ONLY, NETWORK_ONLY and PASSIVE.

Tune accuracy through the profile rather than raw thresholds - the thresholds are the field-tuned part, and the profile is the supported way to move them.

Service configuration

foregroundService keeps capture alive in the background. startOnBoot defaults to true, so tracking resumes after a reboot; stopOnTerminate defaults to false.

trackIt.state          // StateFlow<TrackItState>
trackIt.events         // SharedFlow<TrackItEvent>
trackIt.liveTrack()    // Flow<LiveTrackUpdate>

Events cover Location, LocationRejected, MotionChange, ActivityChange, EnabledChange, ProviderChange, Heartbeat, PowerSaveChange, GeofenceAdded, GeofenceRemoved, GeofenceEntered, GeofenceExited, SessionInterrupted, Diagnostic and Error.

Handling every case is the point - a handler covering four of fifteen makes silence meaningless.

Reading stored data

getPoints() and getSessions() query what was captured. buildTrack() and exportGeoJson() turn it into something you can render or send onward. addGeofence() manages up to 19 system fences.

Debug builds skip the licence check entirely, so you can evaluate the whole SDK before buying.

Known gap, stated plainly

A release build currently calls ready() and fails with licenseMissing: the Android licence verifier is not shipped yet. The backend issues tokens today, and the iOS SDK verifies them today. Android verification is in progress.

If you are preparing an Android release, talk to us before you ship so we can sequence it with your build.

Every Field Track 360 licence is verified on the device, with no network call. The token carries its own signature, the SDK carries the public key, and the check happens locally in milliseconds.

The trade we made

We also check periodically to see whether a licence has been revoked. That check can fail - no signal, a flat DNS, our own outage. When it does, the SDK keeps working on its cached verdict.

That is deliberate, and it costs us something: a revoked licence can survive until the device next reaches the network. We think that is the right side to fail on. A field team's tracking going dark mid-shift because a server blinked is a far worse outcome than a licence lasting a few hours longer than it should.

What it means for you

Your app starts tracking on a plane, on first launch, in a tunnel, after a reboot. There is no licence server in the path of your users doing their jobs.

An application key licenses one app identifier - your Android applicationId or your iOS CFBundleIdentifier - on both platforms.

Why is it bound to the identifier? Because the identifier is cryptographically signed into the token itself. That is what makes a key impossible to copy into a second app: change the identifier and the signature no longer matches. It also means the binding cannot be edited afterwards, by us or by anyone else.

Debug and staging builds

Variants are included, as long as they extend your identifier with a dot. com.acme.app.dev and com.acme.app.staging are covered by a key for com.acme.app. com.acme.appX is a different application and is not - the dot is what separates a variant from a namesake.

When the identifier changes

It happens: a rebrand, a store migration, a typo caught late. Generate a corrected key from your account and the old one is revoked automatically. There is a limit per plan, because a revoked key still verifies offline, and support can help beyond it.