Using the SDK

Trip Manager configuration

The trip manager must be configured before it can be used. To upload trip data, the current mobile device must be activated for data collection through the Portal. This is to ensure trip data can be analyzed properly on the IMS backend. 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 set it through initImsTripManager()

Trip manager initializer has next parameters: Identity, iosUploadRoutes, iosFeatures, iosTripTelemetries, iosProviders, androidTripDetectors, androidTripValidators, androidTripTelemetries. See an example of how to initialize the Ims Trip Manager:

import { 
      initImsTripManager, 
      AndroidTripDetector, 
      AndroidTripValidator, 
      AndroidTripTelemetry, 
      SamplingRate, 
      IosFeature, 
      IosUploadRoute, 
      IosTripTelemetry, 
      IosProvider, 
      Identity 
} from "ims-react-native/src";
 
const identity = new Identity("API_KEY", "EXTERNAL_REFERENCE_ID");
const androidTripDetectorList = [AndroidTripDetector.ACTIVITY, AndroidTripDetector.GEOFENCE];
const androidTripValidatorList = [AndroidTripValidator.PHONE];
const androidTripTelemetry = [AndroidTripTelemetry.LOCATION,
                              AndroidTripTelemetry.SPEED,
                              AndroidTripTelemetry.DISTRACTED_DRIVING];
const featureList = [IosFeature.PHONE_ONLY_VALIDATOR, IosFeature.GEOFENCE];
const uploadRoadList = [IosUploadRoute.ANY_NETWORK];
const iosTripTelemetry = [IosTripTelemetry.SPEED,
                          IosTripTelemetry.GPS,
                          () => IosTripTelemetry.ACCELEROMETER(SamplingRate.ONE_HZ),
                          () => IosTripTelemetry.GYROSCOPE(SamplingRate.ONE_HZ),
                          () => IosTripTelemetry.MAGNETOMETER(SamplingRate.ONE_HZ),
                          () => IosTripTelemetry.USER_ACCELERATION(SamplingRate.ONE_HZ),
                          () => IosTripTelemetry.GRAVITY(SamplingRate.ONE_HZ)];
const iosProvider = [IosProvider.DISTRACTED_DRIVING_RECORD_PROVIDER];
 
initImsTripManager(identity, uploadRoadList, featureList, iosTripTelemetry, iosProvider, androidTripDetectorList, androidTripValidatorList, androidTripTelemetry)
      .then((result: string) => console.log(result))
      .catch((error: Error) => {
        console.log("Error on init ImsTripManager: " + error.message);
      });

Identity

The host application shares the identity of its currently authenticated user by sharing an Identity object with the SDK. An Identity is constructed with the host application's API Key and the host application's unique user identifier, provided during the enrolment process.

IosUploadRoute

The host application can choose upload route for uploading trip files which can be passed during the initialization of the SDK.

[IosUploadRoute.WIFI_ONLY].This upload route uploads data only when connected to a WiFi.

[IosUploadRoute.ANY_NETWORK].This upload route uploads data when connected to any network.

IosFeature

The features: [IosFeature] parameter of TripDetectionManager's initializer specifies which features are used for Trip Detection and Trip Validation. A combination of Trip Detectors and Trip Validators can be passed into the initializer to meet the needs of the App. Simply declare all IosFeature components that are needed.

A standard setup would include at least one Trip Detector and one Trip Validator. For example, a phone only trip detection configuration would include [IosFeature.GEOFENCE] and [IosFeature.PHONE_ONLY_VALIDATION].

Trip Detection

IosFeature.GEOFENCE: To use geofences for trip detection, pass in [IosFeature.GEOFENCE]. This feature provides trip detection using Core Motion and Core Location functionalities.

IosFeature.BLUETOOTH: To use Bluetooth devices for trip detection, pass in [IosFeature.BLUETOOTH]. This feature uses Core Bluetooth functionality to have trip detection using a bluetooth device (i.e. wedge).

NOTE: If there is no Trip Detection Feature parameter passed in the configuration, Trip Detection functionality will be limited.

Trip Validation

Starting with the SDK 1.15.0, the host app can provide the trip validation features as in the example above during the initialization of SDK.

IosFeature.PHONE_ONLY_VALIDATION: To use phone-only trip validation feature, pass in [IosFeature.PHONE_ONLY_VALIDATION]. This feature allows a trip to be validated using the onboard sensors of the phone.

IosFeature.DEVICE_VALIDATION: To use Bluetooth devices for trip validation feature, pass [IosFeature.DeviceValidation]. This feature allows a trip to be validated by the presence of an associated Bluetooth device during the trip.

NOTE: If there is no Trip Validation Feature parameter passed in the configuration, trips will be validated as soon as they are detected.

IosTripTelemetry

Telemetry events add additional information to the recorded trip.

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

IosTripTelemetry.GPS: Default, always recorded: fine location from GPS and other location sources.

IosTripTelemetry.SPEED: Default, always recorded: vehicle speed.

IosTripTelemetry.ACCELEROMETER: Phone accelerometer readings at SamplingRate.

IosTripTelemetry.GYROSCOPE: Phone gyroscope readings at SamplingRate.

IosTripTelemetry.GRAVITY: Phone gravity direction at SamplingRate.

IosTripTelemetry.USER_ACCELERATION: Phone accelerometer readings at SamplingRate.

IosTripTelemetry.MAGNETOMETER: Phone magnetometer readings at SamplingRate.

IosTripTelemetry.ACTIVITY: Phone activity reading at SamplingRate.

AndroidTripDetector

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.

AndroidTripDetector.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. Permissions: Background location.

AndroidTripDetector.ACTIVITY: Triggers start of possible trip when Android reports the phone is probably in a moving car. Permissions: Activity.

AndroidTripDetector.DEVICE: Triggers start of possible trip when an associated Bluetooth device is detected. Permissions: Bluetooth, background location.

AndroidTripDetector.AWARENESS: See more here.

AndroidTripDetector.CAR_AUDIO: Auto-detects the presence of car audio.

AndroidTripValidator

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.

AndroidTripValidator.PHONE: Start: Cancels recording if the driver is walking. End: Stops recording when the driver starts walking. Permissions: Activity.

AndroidTripValidator.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. Permissions: Bluetooth, location.

AndroidTripTelemetry

Telemetry events add additional information to the recorded trip.

All events are optional (AndroidTripTelemetry.LOCATION and AndroidTripTelemetry.SPEED are always used even if not specified)

AndroidTripTelemetry.LOCATION: Default, always recorded: fine location from GPS and other location sources. Permissions: Location.

AndroidTripTelemetry.SPEED: Default, always recorded: vehicle speed. Permissions: Location.

AndroidTripTelemetry.DISTRACTED_DRIVING: Detects phone use during a trip. Permissions: Phone status.

AndroidTripTelemetry.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. Permissions: Bluetooth, location.

AndroidTripTelemetry.ACCELEROMETER: Phone accelerometer reading at SamplingRate.

AndroidTripTelemetry.GRAVITY: Phone gravity direction at SamplingRate.

AndroidTripTelemetry.GYROSCOPE: Phone gyroscope readings at SamplingRate.

AndroidTripTelemetry.MAGNETOMETER: Phone magnetometer readings at SamplingRate.

AndroidTripTelemetry.USER_ACCELERATION: Phone accelerometer readings at SamplingRate.

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 initImsTripManager() in your host app first.
Make sure you've created and passed the Notification factory [supplied class name]. The trip manager requires a custom TripNotificationFactory class with an empty constructor.
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.

Configuration Warnings

Trip detectors, validators, and telemetry can all be 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).

PreviousiOS NextTrip Manager

Last updated 10 months ago