> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdesmo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Android FAQ

> Answers to common questions about the Desmo Android SDK.

## 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](/essentials/android-quickstart#customizing-the-notification-optional) 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:

```kotlin theme={null}
// 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.

<Note>
  If notification permission is denied on Android 13+, sessions will still work in the foreground but won't continue in the background.
</Note>

## What is SessionType and when do I use each?

Every session requires a `SessionType` that tells Desmo what the driver is doing:

| SessionType           | When to use                                                 |
| --------------------- | ----------------------------------------------------------- |
| `SessionType.PICKUP`  | Driver is collecting a package from a merchant or warehouse |
| `SessionType.DROP`    | Driver is delivering a package to a customer                |
| `SessionType.TRANSIT` | Driver is traveling between stops (no specific address)     |

```kotlin theme={null}
// 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.

```kotlin theme={null}
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](/essentials/android-logging-debugging) 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:

```kotlin theme={null}
implementation("com.github.kubocreate:desmo-android-sdk:<new-git-tag>")
```

2. Sync Gradle and rebuild your app.
3. 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.