Android Diagnostics and Health Snapshot

Android Diagnostics and Health Snapshot

What the SmartDrive SDK can tell you, and Scope support, about an integration at runtime. Applies to TripWrapper and, identically, to ScopeSDK. Last updated: 12 Oct 2026 for SmartDrive 1.6.9.

Table of contents

1. Overview
2. The diagnostics picture
3. The health verdict
4. Missing protocols
5. The health snapshot in the log
6. Logging and sending logs to support
7. Reading a snapshot

1. Overview

Most SmartDrive support cases used to start with "trips are not recording" and a log that did not say why. The facade answers that question itself, three ways:

• getDiagnostics() returns a point-in-time picture of the integration as a typed object, for a diagnostics screen.
• isHealthy() is the one-line verdict, and getMissingProtocols() the list of integration gaps behind it.
• logHealthSnapshot() writes the whole picture to the log as one block, and the SDK does the same on its own at start, trip start and trip end, so a support log always carries the state that was in force.

The demo app shows this as a status line on its main screen and adds a snapshot to the log whenever the user sends logs.

2. The diagnostics picture

TripWrapperDiagnostics, from getDiagnostics():

Group	Fields	Meaning
Initialisation	isInitialized, initializationTime	A configuration is in effect, accepted by start or restored by initialize, and since when
Session and arming	isAuthorized, isRecordingArmed, isRecording	The host's current answer; whether the facade has the recording service armed; whether a trip is being recorded now
Wiring	missingProtocols, hasTripListener, hasLogSink	Integration gaps (section 4); whether anything listens for trips, information only; whether a Timber tree is planted
Configuration as applied	mode, realtimeSendingEnabled, autoSendEnabled, beaconsEnabled, distractionOnlyTrips, smartDriveVersion	Beacon gating comes from the vehicle the host reports, else from mode
Permissions	requiredPermissions, missingPermissions	The list this configuration needs on this device, and those not granted
Device	locationEnabled, gpsProviderEnabled, ignoringBatteryOptimizations, powerSaveMode, deviceIdleMode	Location services and the GPS provider; battery optimisation state, which can starve GPS while driving; Doze right now
Trips	tripCounts, currentTripId	Local, unsent, failed and delivered counts of finished trips; the id of the trip being recorded, which is in no count
Vehicle	deviceId	The unit serial number the facade would record for: the host's answer when it gives one, else the one remembered from PortalAPI's announcement
Environment	appDescription, deviceDescription	Package and version; manufacturer, model and Android version, for support exports
Verdict	isHealthy	Section 3

Before start, the picture reports only that the facade has not been started.

3. The health verdict

isHealthy is true when all of these hold:

• the facade is initialised;
• the host reports a session, once authenticated() has been called;
• a vehicle is known, once there is a session;
• a Timber tree is planted;
• every required permission is granted;
• location services are on.

Two things are reported but do not count against health: a missing trip listener, because the SDK records and sends without one, and battery optimisation, because it is a warning about reliability rather than a blocker.

4. Missing protocols

The Kotlin host interface is checked by the compiler, so getMissingProtocols() reports only what the compiler cannot see:

Entry	Meaning
TripWrapperHost.isAuthorized() is false after authenticated()	Your app called authenticated() but the host still says nobody is logged in. Usually the host reads a different session store than the login flow writes.
TripWrapperHost.deviceID() returned no unit serial number and PortalAPI has announced none; recording waits for a vehicle	There is a session but no vehicle yet. On PortalAPI this resolves itself moments after login; otherwise your host's deviceID() is returning null.
no Timber tree is planted, SDK logs go nowhere	Plant one in your Application class.

An empty list means everything is wired. Permissions are reported separately, in missingPermissions.

5. The health snapshot in the log

logHealthSnapshot(trigger) writes one block, headed so that support can search for it:

===== TRIPWRAPPER HEALTH SNAPSHOT =====
[WHEN] Trip start
  time: 2026-09-30T07:41:12Z | local 2026-09-30 09:41:12 +0200 (Europe/Riga)
[APP]
  app: com.example.driver 2.3.0(57)
  device: Google Pixel 8, Android 15 (API 35)
[PERMISSIONS]
  required: ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION, ACCESS_BACKGROUND_LOCATION, ACTIVITY_RECOGNITION, POST_NOTIFICATIONS
  missing: none
  location services: on, GPS provider: on
[SDK]
  SmartDrive: 1.6.9
  initialized: true, authorized: true, armed: true, recording: true
  mode: SMART, realtime sending: false, auto-send: true, beacons: false, distraction-only: false
  current trip: id 42
  trips: local 7, unsent 0, failed 0, delivered 6
  device ID: 5BD1FA
  log sink: true, trip listener: true
[SYSTEM]
  battery optimisations ignored: false  ⚠️ Doze can starve GPS while driving
  power save: false, doze: false
  healthy: true

The values above are illustrative. The shape is fixed: five sections, one line per fact, and a warning mark on exactly the lines that stop trips or endanger them: missing permissions, location services off, battery optimisation on. The [WHEN] line says why the block was written: TripWrapper initialized, Trip start, Trip end, or Manual. The time is given in UTC and in the device's local zone, in a fixed format the device's locale cannot change.

The SDK writes a snapshot itself at start, at every trip start and at every trip end. Your app adds one wherever it helps, typically just before exporting logs.

6. Logging and sending logs to support

The SDK logs through Timber. Without a tree it is silent, and getMissingProtocols() says so. Plant one in Application.onCreate, before initialize and start.

For a support export you want the lines in a file. The demo's FileLoggingTree writes one file per day under the app's cache directory, prefixed with the device and app description, and keeps the last seven days of files. Its Send Logs button calls logHealthSnapshot() first, so the last block in the file is a complete picture, then shares the files through a standard share sheet.

When you contact support@scopetechnology.com, attach the log files. The snapshot blocks let support see permissions, location, power state and trip counts at the moments that matter, without a call back for screenshots.

7. Reading a snapshot

What you see	What it means	What to do
missing: ACCESS_BACKGROUND_LOCATION ⚠️	The user granted location "while using the app" only	Request background location in its own dialog; recording waits until it is granted
location services: off ⚠️ trips will NOT record	Location is switched off on the device	Nothing the app can fix silently; tell the user
armed: false with authorized: true and no missing permissions	No vehicle yet	On PortalAPI, wait a moment after login; otherwise check your host's deviceID()
authorized: false after login	The host reads a different session store than the login wrote	Fix the host
log sink: false	No Timber tree	Plant one; you will not see the other lines without it
battery optimisations ignored: false ⚠️	The app is subject to Doze	See the battery optimisation guidance; trips may start late or stop on some phones
unsent 3, failed 2 and they never change	Retry is off	resendFailedTrips = true, or a button calling retryFailedTrips(), which sends them regardless of that setting since SmartDrive 1.6.9