Skip to main content

​
What happens when the app goes to background?

The SDK automatically continues tracking when the app is minimized or the screen turns off. When you call startSession(), the SDK starts a foreground service that:
  • Keeps collecting location and sensor data
  • Shows a notification (required by Android)
  • Prevents Android from killing the app
When you call stopSession(), the service stops and the notification disappears. This means drivers can put their phone in their pocket during a delivery and tracking continues uninterrupted.

​
Why do I see a notification when recording?

Android requires apps to show a notification when running in the background. This is a platform rule, not a Desmo requirement. The notification tells users “this app is doing something” and lets them stop it if needed. By default, it shows a generic icon with “Recording Active” text. You can customize it with your branding using Desmo.configureForegroundService(). See the quickstart guide for details.

​
Do I need notification permission?

On Android 13+, yes. You need POST_NOTIFICATIONS permission to show the background tracking notification. Use the SDK helpers to check and request this: 
// Check if notifications are allowed
if (!Desmo.canShowNotifications(context)) {
    // Request permission
    val permissions = Desmo.getForegroundServicePermissions()
    requestPermissions(permissions)
}
On Android 12 and earlier, no runtime permission is needed for notifications.
If notification permission is denied on Android 13+, sessions will still work in the foreground but won’t continue in the background.

​
What is SessionType and when do I use each?

Every session requires a SessionType that tells Desmo what the driver is doing:
SessionTypeWhen to use
SessionType.PICKUPDriver is collecting a package from a merchant or warehouse
SessionType.DROPDriver is delivering a package to a customer
SessionType.TRANSITDriver is traveling between stops (no specific address)
// Example: Starting a drop-off session
client.startSession(
    deliveryId = "ORDER_123",
    sessionType = SessionType.DROP,
    address = Address.fromRaw("123 Main St, City")
)
For PICKUP and DROP sessions, you should always provide an address. For TRANSIT sessions, the address is optional.

​
Is the SDK safe to run in production?

Yes. The SDK is designed to run continuously during delivery sessions:
  • It batches telemetry to reduce network overhead.
  • It uses efficient system APIs for motion/location and networking.
  • You control which environment it talks to (SANDBOX vs LIVE).
We still recommend starting with a small pilot group and monitoring app performance and crash reports.

​
Will the SDK crash my app?

No. The SDK uses a crash-safe DesmoResult pattern. All public API methods return DesmoResult.Success or DesmoResult.Failure instead of throwing exceptions. This means:
  • SDK errors will never cause an uncaught exception in your app.
  • Your delivery flow always continues, even if the SDK encounters an error.
  • You handle errors explicitly via .onSuccess and .onFailure callbacks.
client.startSession(
    deliveryId = "ORDER_123",
    sessionType = SessionType.DROP,
    address = Address.fromRaw("123 Main St")
).onFailure { error ->
    // Log it, but delivery continues normally
    Log.w("MyApp", "Desmo error (non-fatal): $error")
}

​
What happens if the device is offline?

If the device is temporarily offline:
  • startSession and stopSession will return DesmoResult.Failure if the backend cannot be reached.
  • Telemetry is saved locally to a SQLite database on the device and uploaded automatically when connectivity returns.
Integration tips:
  • Handle DesmoResult.Failure gracefully - don’t block the driver’s delivery flow.
  • Consider allowing drivers to retry stopSession if the first attempt fails.
  • Telemetry data is never lost - the SDK persists and retries automatically.

​
What happens to telemetry if upload fails?

The SDK includes a persistent offline queue:
  1. Telemetry batches are saved to local SQLite storage before upload.
  2. If upload fails (network error, timeout, etc.), the data stays in the queue.
  3. The SDK automatically retries failed uploads when connectivity returns.
  4. Data is only deleted from the queue after successful upload.
This ensures no data loss even in poor network conditions or if the app is killed mid-session.

​
Can I disable or remove the SDK?

Yes. You can:
  • Stop calling Desmo.setup and any session APIs.
  • Remove the desmo-android-sdk dependency from your Gradle configuration.
If you need to immediately disable ingest on the backend side, you can revoke the publishable key in the Desmo dashboard.

​
How do I test without affecting production data?

Use:
  • A sandbox publishable key (pk_sandbox_...).
  • DesmoEnvironment.SANDBOX when calling Desmo.setup.
This keeps test sessions and telemetry separate from live deliveries. You can create dedicated sandbox projects/tenants as needed.

​
How do I see what the SDK is doing?

  • Enable logging during development (it’s disabled by default for production safety).
  • Watch Logcat with tag filter DesmoSDK for:
    • Session start/stop events.
    • HTTP requests and responses.
    • Any warnings or errors emitted by the SDK.
  • Use the Android Logging, Debugging & Troubleshooting guide for a detailed checklist.

​
How do I upgrade the SDK?

When a new version is released:
  1. Update the version in your Gradle dependency:
implementation("com.github.kubocreate:desmo-android-sdk:<new-git-tag>")
  1. Sync Gradle and rebuild your app.
  2. Re-run your tests and core delivery flows.
Because integration goes through Desmo.setup, startSession, and stopSession, most changes are backwards compatible as long as you stay within the same major version.

​
Who do I contact for support?

For API keys, backend configuration, or integration questions:
  • Reach out to your Desmo contact.
  • Or use the support channel linked from the Desmo dashboard.