> ## 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 Logging, Debugging & Troubleshooting

> See what the Desmo Android SDK is doing under the hood and debug common issues.

## Enabling SDK logging

The Desmo Android SDK includes lightweight logging to help you understand what it's doing.

Logging is controlled by the `loggingEnabled` flag on `DesmoConfig`, which defaults to `false` for production safety. When enabled, the SDK logs messages such as:

* When `Desmo.setup` succeeds or fails.
* When sessions start and stop.
* When HTTP requests are sent and responses are received.

Because `DesmoConfig` is created internally when you call `Desmo.setup`, you typically control logging by choosing whether you're in a debug or release build and, if needed, exposing a small wrapper around setup.

Example (simple setup using defaults):

```kotlin theme={null}
Desmo.setup(
    context = applicationContext,
    apiKey = "pk_sandbox_XXXXXXXXXXXXXXXX",
    environment = DesmoEnvironment.SANDBOX
    // loggingEnabled defaults to false - enable explicitly during development
)
```

You will see messages like:

```text theme={null}
D/DesmoSDK: Setup successful pointing to: https://api.getdesmo.io
D/DesmoSDK: Starting session for delivery: ORDER_12345
D/DesmoSDK: Session started successfully: SESSION_ID
D/DesmoSDK: Foreground service started with default config
```

During development, we recommend enabling logging to verify the SDK is working correctly.

## Where logs appear

The SDK uses Android's native `Log` class with the tag `DesmoSDK`, so logs show up in:

* Android Studio's **Logcat** when you run the app from Android Studio.
* Device logs collected via your logging/observability pipeline.

To filter for Desmo logs only, use:

```bash theme={null}
adb logcat -s DesmoSDK
```

Or in Android Studio's Logcat panel, filter by the tag `DesmoSDK`.

During integration, keep logging **enabled** in sandbox builds so you can verify what the SDK is doing.

## Debugging common issues

### 1. `Desmo.client` is null

Symptom:

* Your code prints `"Desmo SDK is not configured"` when you try to use `Desmo.client`.

Checklist:

* Ensure `Desmo.setup` is called:
  * Exactly once.
  * Early in the app lifecycle (e.g. in your `Application` `onCreate`).
* Confirm the key starts with `pk_` and is not empty.
* Look for a log like:

```text theme={null}
[DesmoSDK] Setup failed: ...
```

If setup fails, fix the key and rebuild.

### 2. Session start fails

Symptom:

* `startSession` returns `DesmoResult.Failure` with an error.

Checklist:

* Confirm the publishable key you are using is:
  * Valid and not revoked.
  * Created for the environment you selected (`SANDBOX` vs `LIVE`).
* Confirm the device has network connectivity.
* Check the error in your `.onFailure` handler for details.
* Check your backend/logs for more detailed error messages tied to that key.

<Note>
  The SDK uses a crash-safe `DesmoResult` pattern. Errors are returned as `DesmoResult.Failure` rather than thrown, so your app will never crash due to SDK errors.
</Note>

### 3. Session stop fails

Symptom:

* `stopSession` returns `DesmoResult.Failure` with an error.

What the SDK does:

* Flushes telemetry via `telemetry.flush()` and `telemetry.stop()` before notifying Desmo's backend that the session should stop.
* If the network call fails, it keeps the internal state as **recording** so you can retry `stopSession()`.
* Telemetry is saved locally and retried automatically when connectivity returns.

Checklist:

* Try stopping again once connectivity is restored.
* Inspect logs for HTTP status codes or network errors.

### 4. No data appears in Desmo

Symptom:

* `startSession` / `stopSession` succeed, but you don't see sessions/insights in Desmo.

Checklist:

* Confirm you are using the **same environment and tenant** as the dashboard you're looking at.
* Check for any rate limiting or 4xx/5xx errors in the logs.
* Share session IDs from your logs with the Desmo team to trace them end-to-end.

### 5. No notification appears / background tracking stops

Symptom:

* Session starts but no notification is shown.
* Tracking stops when the app goes to background.

Checklist:

* **Android 13+**: Ensure `POST_NOTIFICATIONS` permission is granted:

```kotlin theme={null}
if (!Desmo.canShowNotifications(context)) {
    // Request permission
}
```

* Check logs for:

```text theme={null}
D/DesmoSDK: Foreground service started with default config
```

* Verify the app has the `FOREGROUND_SERVICE` permission in `AndroidManifest.xml` (the SDK declares this, but ensure no tools are stripping it).

### 6. Custom notification not showing

Symptom:

* You called `configureForegroundService()` with a custom notification but it doesn't appear.

Checklist:

* Ensure you created the **notification channel** before starting a session (required on Android 8+).
* The notification must have a valid **small icon** resource.
* Call `configureForegroundService()` **after** `Desmo.setup()` but **before** `startSession()`.

## Integration checklist

Use this as a quick pre-flight check before shipping:

1. **Setup**
   * [ ] `Desmo.setup` is called exactly once at app startup.
   * [ ] `Desmo.bindToProcessLifecycle()` is called after setup (recommended).
   * [ ] You use a **publishable** key starting with `pk_`.
   * [ ] The environment (`SANDBOX` / `LIVE`) matches the keys you created.
2. **Permissions**
   * [ ] Location permissions (`ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`) are requested and granted.
   * [ ] On Android 13+: `POST_NOTIFICATIONS` permission is requested for background tracking.
   * [ ] You use `Desmo.hasRequiredPermissions()` and `Desmo.canShowNotifications()` to check.
3. **Session lifecycle**
   * [ ] `startSession` is called when a delivery begins with `sessionType` specified.
   * [ ] `stopSession` is called when the delivery completes.
   * [ ] Both calls return `DesmoResult.Success` in your test flows.
   * [ ] Your app handles `DesmoResult.Failure` gracefully (doesn't block delivery).
4. **Background operation**
   * [ ] A notification appears when a session starts.
   * [ ] Tracking continues when you minimize the app or turn off the screen.
   * [ ] The notification disappears when the session stops.
   * [ ] (Optional) Custom branding configured via `configureForegroundService()`.
5. **Logging**
   * [ ] Logging is enabled in sandbox builds.
   * [ ] You can see Desmo logs in Logcat (filter by tag `DesmoSDK`).
6. **Backend visibility**
   * [ ] You can see created sessions in the Desmo dashboard or API using the same environment and tenant.

If any box is unchecked, fix that item before rolling out broadly to drivers.