Trip Manager Configuration

The trip manager must be configured before it can be used. This is a one-time operation; the SDK remembers its configuration and, once configured, the trip manager initializes itself automatically.

Trip configuration settings

You can configure the trip manager any time during your app setup; once it has been configured, it does not need to be configured ever again unless you change the settings.

• Note that once the trip manager has been configured, you must also call enableTripManager() once before it will actually start detecting and/or recording trips.

Trip manager configuration uses ImsTripConfiguration. You can get the current configuration as ImsTripManager.configuration but you can only set it through ImsTripManager.configureTripManager().

if (!ImsTripManager.isConfigured) {
    ImsTripManager.configureTripManager( context,
        ImsTripManager.Builder()
            .setTripDetectors(TripDetector.ACTIVITY, TripDetector.GEOFENCE, TripDetector.AWARENESS, TripDetector.DEVICE)
            .setTripValidators(TripValidator.PHONE)
            .setTripTelemetry(TripTelemetry.LOCATION, TripTelemetry.SPEED,
                              TripTelemetry.DISTRACTED_DRIVING, TripTelemetry.ASSOCIATED_VEHICLE)
            .setTripNotification(MyNotificationFactory::class.java)
            .build()
    )
}

Trip manager configuration is split into Detectors, Validators, Telemetry, and Notification settings.

TripDetectors

Detectors are used to detect the start of a possible trip.

• Unless your app starts trip recording explicitly, you must specify at least one of GEOFENCE, ACTIVITY, and/or DEVICE, or else no trips will be recorded.

Setting	Description	Permissions
TripDetector.GEOFENCE	Triggers start of possible trip when the phone travels a certain distance, or comes within about 20 meters of where the car was at the end of the previous trip.	Background location
TripDetector.ACTIVITY	Triggers start of possible trip when Android reports the phone is probably in a moving car.	Activity
TripDetector.DEVICE	Triggers start of possible trip when an associated Bluetooth device is detected	Bluetooth, background location

TripValidators

Validators are used to confirm the start and end of an actual trip.

• Unless your app stops trip recording explicitly, you must specify the PHONE and/or DEVICE validator, or else no trips will be recorded.

Setting	Description	Permissions
TripValidator.PHONE	Start: Cancels recording if the driver is walking. End: Stops recording when the driver starts walking.	Activity
TripValidator.DEVICE	Start: Verifies that the associated Bluetooth device is still present after the car starts moving. End: Detects the end of a trip when the associated Bluetooth device is no longer detected.	Bluetooth, location

TripTelemetry

Telemetry events add additional information to the recorded trip.

• All events are optional (TelemetryEvent.GPS and TelemetryEvent.SPEED are always used even if not specified)

Setting	Description	Permissions
TripTelemetry.LOCATION	Default, always recorded: fine location from GPS and other location sources.	Location
TripTelemetry.SPEED	Default, always recorded: vehicle speed.	Location
TripTelemetry .DISTRACTED_DRIVING	Detects phone use during a trip.	Phone status
TripTelemetry .VERIFIED_VEHICLE	If a vehicle is associated to a particular Bluetooth (or other) device, and that device is detected in the car during the trip, then the ID of the corresponding vehicle is recorded in the trip data.	Bluetooth, location
TripTelemetry.x (others)	Depending on your scoring requirements you may also wish to track additional sensors such as accelerometer, gyroscope, or magnetometer. Reserved for future use; these are currently ignored by the DriveSync server.	- none -

Distracted Driving

The distracted driving component monitors use of the phone during a trip. Trip scoring is enhanced by using the distracted driving module, but this also requires special permissions so it is optional.

To use distracted driving,

1. Add a dependency on distracteddriving to your app's build.gradle:

   implementation 'com.intellimec.mobile.android:distracteddriving:3.11.0'

2. Add the following to the app's proguard-rules:

   -keep class com.intellimec.mobile.android.distracteddriving.DistractedDrivingRecordProvider

3. Specify TripTelemetry.DISTRACTED_DRIVING in the trip manager configuration

4. Ask the user to grant the READ_PHONE_STATE permission. This permission is required for the SDK to detect phone calls.

Notification Factory

Trip recording needs to happen automatically in the background without user interaction. On Android this means it runs in a foreground service, which in turns means it requires a notification to inform the user we're using background resources.

Notifications are shown while the SDK evaluates the start of a possible trip as well as during recording.

• The notification factory must be specified or else no trips will be recorded.

• The notification factor class must not be obfuscated. You should to add a line like this to your proguard-rules file : -keep class [MyNotificationFactory].** { *; }

Setting	Description	Permissions
Class<TripNotificationFactory>	The host app must provide its own implementation of the TripNotificationFactory interface.	Notifications

IMS expects SDK users to fully customize these notifications. To do this, the host app must provide its own implementation of the TripNotificationFactory interface. The SDK will instantiate the class and call the appropriate method as required.

• Potential Trip Notification: This notification is shown the SDK has detected the probably start of a trip but is waiting to verify that it's actually from a moving vehicle. For example, this notification is shown as soon as the geofence detector indicates that the phone is near the car. We use a separate notification for this case so apps can reassure users that, while the trip system is active, it's not in full recording mode yet (the SDK does not save any data collected during this phase). Because of the nature of this notification we recommend using a channel with low importance and without generating noise or vibration.

• Validated Trip Notification: This notification is shown once vehicle motion has been detected. It remains visible throughout the trip. We have found that some drivers prefer a sound at the start of the trip and some drivers require silence.

• Constructor: You must implement this class with a no-parameter (empty) constructor.

A full implementation is available in the SDK Sample App source code. However, for reference, the factory interface looks like this:

interface TripNotificationFactory {
    fun createPotentialTripNotification(context: Context) : Notification
    fun createValidatedTripNotification(context: Context) : Notification
}

The most basic implementation looks like this (you will want to specify the icon, title, and more):

class MyAppNotification: TripNotificationFactory {
    override fun createPotentialTripNotification(context: Context): Notification {
        val notificationIntent = Intent(context, MainActivity::class.java)
        return NotificationCompat.Builder(context, "silentChannel")
            .setContentIntent(PendingIntent.getActivity(context, 0, notificationIntent, 0))
            .setContentInfo("Possible trip detected, checking to see if you are driving")
            .build()
    }
    override fun createValidatedTripNotification(context: Context): Notification {
        val notificationIntent = Intent(context, MainActivity::class.java)
        return NotificationCompat.Builder(context, "noisyChannel")
            .setContentIntent(PendingIntent.getActivity(context, 0, notificationIntent, 0))
            .setContentInfo("Your trip is being recorded")
            .build()
    }
}

Errors and Warnings

Configuration Errors

ImsTripManager validates its configuration every time it's set or changed. If there's a code-related problem it throws an exception so that programmers can detect and fix the problem early in the development cycle.

The error messages are designed to be informative; in most cases they provide links directly to the relevant section in these documents.

Some of these errors are:

• Trip manager must be configured before it is enabled. Call ImsTripManager.setConfiguration() first. See: https://sdk.ims.tech/trip-detection-and-recording/android/trip-manager-configuration

• ImsTripConfiguration trip notification factory [supplied class name]. The trip manager requires a custom TripNotificationFactory class with an empty constructor. See https://sdk.ims.tech/trip-detection-and-recording/android/trip-manager-configuration#notification-factory

• Cannot instantiate com.intellimec.mobile.android.distracteddriving.DistractedDrivingRecordProvider. Make sure you've added the distracteddriving dependency to your app's build.gradle: implementation 'com.intellimec.mobile.android:distracteddriving:x and the following line to your app's proguard-rules.pro: -keep class com.intellimec.mobile.android.distracteddriving.DistractedDrivingRecordProvider See: https://sdk.ims.tech/trip-detection-and-recording/android/trip-manager-configuration#distracted-driving

Configuration Warnings

Trip detectors, validators, and telemetry can all be configured independently, or even not used at all. While this provides great flexibility, it also means it's possible to configure the trip manager in such a way that it doesn't give the desired results.

Whenever you set or change the configuration, ImsTripManager issues warnings about possible problems. These are reported as log messages.

• Warning: No trip validators were enabled

• Warning: No trip detectors were enabled

• Warning: ACTIVITY detector specified with no matching PHONE validator

• Warning: DEVICE detector specified with no matching DEVICE validator

• Warning: PHONE validator specified with no matching ACTIVITY detector

• Warning: DEVICE validator specified with no matching DEVICE detector

Runtime Problems

Aside from the configuration warnings, the trip manager also checks for problems at runtime.

The most common runtime problem is missing permissions. Android lets uses revoke permissions at any time after they're granted; these problems may appear while the trip recorder is working in background.

Runtime problems are reported through the trip status listener (they are also logged).