SmartDriveDemo Android — App Overview

SmartDriveDemo Android — App Overview & Component Reference

The Android reference app for the Scope SDKs. Source: SmartDriveDemo-Android. Companion pages: Android Consolidated SDK documentation, Android Simplified SDK Integration. Last updated: 12 Oct 2026 for Consolidated SDK 1.1.9.

SmartDriveDemo is a small app that logs in to the ConnectedCar Portal, records trips through the consolidated SDK in either smart or beacon mode, shows the trip live, fetches recorded trips back from the Portal, and exports its logs. It exists to be copied from: five files make up the whole SDK integration, and everything else is ordinary app code.

Table of Contents

1. Architecture at a glance
2. Frameworks, packages & required configuration
3. Requirements & running the demo
4. SDK integration layer
5. App lifecycle — MyApp.kt
6. Trip data & UI
7. Beacons
8. Diagnostics, logs & export
9. Authentication
10. Wellness (optional module)
11. Key flows
12. Adopting this app as your integration template
13. Where to start

1. Architecture at a glance

Screens (MainActivity, LoginActivity, BeaconsActivity, WellnessActivity)
        │  observe LiveData
        ▼
SmartDriveHelper          ← turns the SDK's four callbacks and its tripCounts flow into LiveData; wraps the five calls
        │
        ▼
ScopeSDK  (com.scopetechnology:sdk)
   ├─ TripWrapper (SmartDrive)    ← recording, sending, diagnostics
   ├─ PortalAPI Base              ← login, vehicles, trips; announces the selected vehicle
   ├─ BLE                         ← beacon scanning and pairing (BEACON mode)
   └─ Wellness                    ← vital signs (optional)

Two files the app owns describe the integration to the SDK: AppScopeHost.kt answers whether a user is logged in, and AppScopeConfiguration.kt holds the typed configuration. The SDK asks the host whenever something may have changed, so the app never pushes state into it.

2. Frameworks, packages & required configuration

Adding the package dependency

implementation 'com.scopetechnology:sdk:1.1.9'

The consolidated SDK bundles SmartDrive 1.6.9, PortalAPI Base 1.2.9, BLE 1.5.6, Wellness 1.1.4 and shared classes 1.1.7. The individual coordinates are listed, commented out, in app/build.gradle for apps that need only some of them. Credentials for GitHub Packages go in gradle.properties as github_username and github_key; the root build.gradle adds the repository.

Required app configuration

• minSdk 27, targetSdk 35, compileSdk 36, which the SDKs require since 1.1.6; Android Gradle Plugin 9.3.3 on Gradle 9.5, with Kotlin built into AGP.
• packaging.jniLibs.useLegacyPackaging = true for the Wellness SDK's native libraries.
• The manifest declares POST_NOTIFICATIONS. It does not declare READ_PHONE_STATE, because the demo leaves phone-call distraction detection off; turn that on and the declaration is needed.
• The default Portal server is SERVER in app/build.gradle; the login screen's Set server button overrides it at runtime.

Maintaining versions

The one version to bump is the consolidated SDK's. The comment above the dependency lists what each release bundles; keep it in step so the file documents itself.

3. Requirements & running the demo

Requirements

• A phone. An emulator can log in, but without real movement it records nothing worth sending.
• A test Portal account from Scope support, and GitHub Packages access for the build.
• For beacon mode, a Scope beacon or MHub paired to the vehicle.

Run it

1. First run: choose Smart or BLE. Smart needs no hardware; BLE needs a paired beacon. The choice is asked on the first run only.
2. Log in. Set server changes the backend first, if needed.
3. Grant the permission dialogs in order. For location choose Allow all the time; background location comes as its own dialog on Android 11 and later.
4. The status line reads "SmartDrive 1.6.9: ready to record". If it says "waiting for", it names what is missing.
5. Mock IN_VEHICLE starts a trip in smart mode without driving: the SDK receives a simulated "in vehicle" activity, then records real GPS positions. The trip ends 5 minutes after the phone stops moving, and a trip shorter than 102 metres is discarded, so walk or drive a little. A real drive starts a trip on its own.
6. Local trips shows what is still on the phone: Processing counts a trip from its upload until the backend confirms it, Failed counts trips whose upload failed, and Resend failed trips sends those again. To test that button, switch Auto-resend failed trips off first and end a trip with the backend unreachable; with it on, the SDK resends the trip itself as soon as a network is back.
7. Fetch trips lists the recorded trips once they are uploaded. Send Logs shares the log files with a health snapshot at the end.

In BLE mode, pair a beacon on the Beacons screen first; trips record only while it is in range.

4. SDK integration layer

Everything the SDK needs from the app, in app/src/main/java/com/scope/smartdrivedemo/:

File	Role
AppScopeHost.kt	isAuthorized() answers from PortalAPI. deviceID() and onBeaconTripStart() keep their defaults; the vehicle's unit type is not a host question, an app without PortalAPI passes it with the vehicle to ScopeSDK.vehicleSelected.
AppScopeConfiguration.kt	Mode from the first-run choice, app name and abbreviation, the notification activity, and four engine settings: retry failed uploads, distraction detection on with phone-call detection off and a 5 km/h minimum speed.
SmartDriveHelper.kt	Wraps initialize, start, authenticated, permissionsChanged and logout, with one host instance; sets the four callbacks once and exposes tripInProgress, tripDistanceKm, tripDuration, currentSpeedKmh and, from the SDK's tripCounts flow, tripCounts as LiveData; diagnostics, local trips, retry, the mock, and the vehicle wrappers.
PermissionsUtil.kt	Filters a fixed request order through ScopeSDK.requiredPermissions(configuration) and returns the groups still to request.
MyApp.kt	Plants the log tree, initialises PortalAPI, initializes and starts the SDK, gates the other SDKs on permissions, logs out of everything.

5. App lifecycle — MyApp.kt

1. Launch. Plant FileLoggingTree, initialise PortalAPI with the server URL, app name and version, then ScopeSDK.initialize(...), which restores the configuration the last start accepted so recording resumes at once after a reboot or a service restart, then ScopeSDK.start(...) with the app's configuration. This runs before login and before any permission dialog. On the first run the mode is chosen after this, in AppTypeActivity, which calls ScopeSDK.start(...) again so the configuration in effect follows the choice; equal settings change nothing. If a returning user already has every permission, configure Wellness and BLE right away.
2. Login happens in LoginActivity, which calls ScopeSDK.authenticated() after a successful login.
3. Permissions granted. onAllPermissionsGranted() calls ScopeSDK.permissionsChanged(), configures Wellness, and in BLE mode configures the beacon manager and starts the scanner service. MainActivity calls it after the last permission dialog.
4. Logout, from the button or PortalAPI's logout broadcast when a session expires: PortalAPI, ScopeSDK.logout(), Wellness, BLE in that order, then the login screen.

The order of launch, login and permission grants does not matter to the SDK; each step re-checks.

6. Trip data & UI

MainActivity observes the helper's LiveData: the status label switches between RECORDING and IDLE, and distance, duration and speed update on every position. The SDK status line comes from ScopeSDK.getDiagnostics(): "ready to record" when healthy, otherwise "waiting for" the missing protocols and permissions. Local trips shows the finished trips the SDK still holds on the phone, from ScopeSDK.tripCounts: Processing, uploaded and kept until the backend confirms it processed them, and Failed; Auto-resend failed trips is the SDK's own retry of failed uploads, SmartDriveConfiguration.resendFailedTrips, on by default in the demo; off, a failed trip stays on the phone, which is how to test the button next to it. Resend failed trips calls ScopeSDK.retryFailedTrips(), which sends whatever the switch says and also sends quarantined trips (SmartDrive 1.6.9), and each result comes back through onTripSent. A trip the backend rejected five times is quarantined: it stays in Failed and the SDK does not resend it on its own.

Fetch trips asks PortalAPI for the selected vehicle's trips of the last seven days with their events, lists them with acceleration, braking and cornering counts, and reports a trip still in progress. SplashActivity refreshes the user and the tenant's exception thresholds on every launch of a logged-in user.

7. Beacons

In BLE mode BleHelper.configure() selects the beacon manager (SBeaconManager; add MHubManager for MHub devices) and registers an events receiver for in-range, paired and my-car-found events; MyApp starts the foreground scanner service once permissions are granted. BeaconsActivity, reachable from the Beacons button that is visible in BLE mode only, scans for beacons and pairs one to the selected vehicle. SmartDrive then records only while that beacon is in range. Details in the Android SBeacon framework pages.

8. Diagnostics, logs & export

• SmartDriveHelper.diagnostics() returns the SDK's point-in-time picture; the status line is built from it.
• Send Logs calls ScopeSDK.logHealthSnapshot(), so the last thing in the log is the full snapshot, then shares the log files.
• FileLoggingTree is a Timber tree writing one file per day under the app's cache directory, with a device and app header, and keeping the last seven days of files. The SDKs log through Timber, so their lines land in the same files.

The full reference for what the SDK reports is Android Diagnostics and Health Snapshot.

9. Authentication

LoginActivity calls BasePortalApi.standardAuth(username, password), then ScopeSDK.authenticated(). PortalAPI selects a default vehicle when it loads the user and announces it to the SDK; the app writes no vehicle code. SplashActivity checks BasePortalApi.isLoggedIn() at launch and skips the login screen for a returning user.

10. Wellness (optional module)

WellnessHelper.configureWellness() fetches the licence key from the Portal's mobile settings once and configures WellnessManager. WellnessActivity extends the SDK's WellnessBaseActivity and receives vital signs, images and errors. MainActivity requests the camera permission before opening it. Details in the Android Wellness framework page.

11. Key flows

Typical integration sequence

Application.onCreate
  Timber.plant(...)  →  BasePortalApi.init(...)  →  ScopeSDK.initialize(...)  →  ScopeSDK.start(...)
First run, before login
  AppTypeActivity sets the mode  →  ScopeSDK.start(...) again
Login
  BasePortalApi.standardAuth(...)  →  ScopeSDK.authenticated()
  PortalAPI loads the user, selects a vehicle, announces it  →  the SDK remembers it
Permissions
  request the groups PermissionsUtil returns  →  ScopeSDK.permissionsChanged()
Fetch trips, on every resume and from the button
  ScopeSDK.confirmProcessingTrips { BasePortalApi.getTrips(...) }
Recording arms; trips arrive through the four callbacks
Logout
  BasePortalApi.logout()  →  ScopeSDK.logout()

A trip, start to Portal. The SDK detects movement (or the paired beacon), onTripStarted fires, onTripUpdated follows every position, onTripEnded fires when the phone has stood still for the trip-end timer, the trip is sent because autoSend is on, and onTripSent reports the result. Fetch trips shows it once the Portal has it.

12. Adopting this app as your integration template

Copy the five files in section 4 into your app and adjust:

• AppScopeHost.kt: answer isAuthorized() from your session. Leave deviceID() alone if PortalAPI selects your vehicle; override it if your app picks the vehicle by a rule PortalAPI does not know. An app without PortalAPI leaves it alone too and calls ScopeSDK.vehicleSelected when the user picks a vehicle.
• AppScopeConfiguration.kt: your mode, names and notification activity, then only the engine settings you change.
• PermissionsUtil.kt: keep as is, or reorder the groups.
• SmartDriveHelper.kt: keep the callback-to-LiveData shape, or collect ScopeSDK.tripState in Compose instead.
• MyApp.kt: the five calls, in your own Application class.

Then drop what you do not need: the Beacons screen without BLE, the Wellness screen without Wellness, the mock button in production.

13. Where to start

Read Android Simplified SDK Integration once, then open MyApp.kt, AppScopeHost.kt and AppScopeConfiguration.kt in that order. The demo's README repeats this page in shorter form.

Support & licensing

support@scopetechnology.com. The demo is provided for integration reference; the SDKs are proprietary and require licensing.