Using the SDK

Device Activation (aka Phone Registration)

The user's phone must be registered through the Portal before trips recorded on that phone can be uploaded. Depending on the activation method, as selected by the host app, the device may only require one activation.

There is currently a limit of one registered phone per user account. If the same user logs in and registers a second phone, trips from the first phone will no longer get uploaded to the server.

Use the DeviceService to activate the device (register the phone) before you start recording trips.

final identity = Identity(
        apiKey: 'apiKey',
        externalReferenceId: 'externalReferenceId');
await DeviceService.instance.initialize(identity: identity);
await DeviceService.instance.activate();

Control Trip Detection and Recording

The trip detection manager must be initialized when the application starts. To initialize the TripDetectionManager you need to provide the Identity and various platform specific trip detection parameters, which you can learn more about in the Flutter SDK API reference(link) or platform specific documentation for iOS(link) and Android(link).

    await TripDetectionManager.instance.initialize(
        identity: identity,
        iosTelemetryEvents: [
          GpsIosTelemetryEvent(),
          SpeedIosTelemetryEvent(),
          GyroscopeIosTelemetryEvent(SamplingRate.oneHz),
          GravityIosTelemetryEvent(SamplingRate.oneHz),
          AccelerometerIosTelemetryEvent(SamplingRate.oneHz),
          UserAccelerationIosTelemetryEvent(SamplingRate.oneHz),
          MagnetometerIosTelemetryEvent(SamplingRate.oneHz)
        ],
        iosFeatures: [IosFeature.geofence, IosFeature.phoneOnlyValidation],
        iosUploadRoute: IosUploadRoute.anyNetwork,
        iosExternalRecordProviders: [
          IosExternalRecordProvider.distracredDriving
        ],
        androidTripDetectors: [
          AndroidTripDetector.activity,
          AndroidTripDetector.geofence,
        ],
        androidTripValidators: [
          AndroidTripValidator.phone,
        ],
        androidTripTelemetry: [
          LocationAndroidTripTelemetry(),
          SpeedAndroidTripTelemetry(),
          DistractedDrivingAndroidTripTelemetry()
        ]);

Additionally to inititialize the trip detection manager it is required to pass a Notification factory class to in Android platform code.

TripDetectionManager.notificationFactory = MyNotificationFactory::class.java

Enable Trip Detection and Recording

But trip detection and recording does not happen until you explicitly enable it at least once. Use the enableTripDetection method to enable trip detection, recording, and trip file upload. Use the disableTripDetection method to stop, such as when the user logs out.

await TripDetectionManager.instance.enableTripDetection();

Note that once trip detection is enabled, it remains enabled on Android even if the application restarts or the phone reboots. You only need to explicitly re-enable it if you previously disabled it.

Programmatically Starting and Stopping Trips

The trip detection manager must be enabled before the trip recorder can be started or stopped programmatically (see previous section).

await TripDetectionManager.instance.beginTripRecording();

// ...

await TripDetectionManager.instance.endTripRecording();

The start command has no effect if the recorder is already started (or if trip detection is disabled), and the stop command has no effect if the recorder's not already running.

• If you have specified no validator on Android (TripValidator.PHONE and/or TripValidator.DEVICE), then, once started, the trip recorder will continue recording indefinitely until you issue the stop command.

• If you have specified at least one validator on Android, trip recording will stop automatically using the validator, or when you issue the stop command, whichever comes first.

Trip Recording Status

The app can get a Stream that emits an event each time a trip starts or ends.

TripDetectionManager.instance.tripStartedStream().listen((_) {
    print('A trip has started!');
});

TripDetectionManager.instance.tripEndedStream().listen((_) {
    print('The trip has ended!');
});