drivekittripanalysisbridge v1.2.2

DriveKitTripAnalysisBridge

You can use this to access DriveKitCore functions in your React Native app. You can find the documentation here.

Installation

npm install drivekittripanalysisbridge

iOS

Add the following line to your podfile:

target 'my-target' do
  pod 'DriveKitTripAnalysis'
end

Then, run pod install.

Set up

Before being able to use the component, you need to add the native files to your app so they can be compiled with it.

iOS

• Open your projectname.xcworkspace/ by using the following command from the root of your React Native app:

open ios/projectname.xcworkspace

• Then, go to Build Phases and click on the + sign in Compile Sources.
• In the popup window, click on Add Other...
• Select for the DriveKitTripAnalysis.m and DriveKitTripAnalysis.swift files of the package in projectname > node_nodules > drivekittripanalysisbridge > ios and click Open.
• Make sure Create folder references is checked and click on Finish.

The added files should now be on the list in Compile Sources.

DriveKitTripAnalysis needs permissions to work. Add the following to the Info.plist file before the </dict> closing tag:

<key>NSMotionUsageDescription</key>
<string>Motion usage is necessary to access your device's accelerometer</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Location is necessary to detect when you are driving</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location is necessary to detect when you are driving</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Location is necessary to detect when you are driving</string>

To initialize DriveKitTripAnalysis in your app, you must call the initialization methods in the didFinishLaunchingWithOptions method of your application class.

import DriveKitTripAnalysis

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  DriveKitTripAnalysis.shared.initialize(tripListener: self, appLaunchOptions: launchOptions)
...
}

You will notice an error on tripListener. To fix that, add TripListener to the AppDelegate class. It should look like this:

class AppDelegate: UIResponder, UIApplicationDelegate, TripListener {
...
}

Then, add the following methods to the AppDelegate class:

  func tripStarted(startMode: StartMode) {
  }

  func tripPoint(tripPoint: TripPoint) {
  }

  func tripFinished(post: PostGeneric, response: PostGenericResponse) {
  }
  
  func tripCancelled(cancelTrip: CancelTrip) {
  }
  
  func tripSavedForRepost() {
  }
  
  func beaconDetected() {
  }
  
  func significantLocationChangeDetected(location: CLLocation) {
  }
  
  func sdkStateChanged(state: State) {
  }

You might have to import CoreLocation:

import CoreLocation

Usage

Import the class using the following line:

import { DriveKitTripAnalysis } from 'drivekittripanalysisbridge'

Check your configuration

You can check if Trip Analysis SDK is well configured with the following method:

isDriveKitTripAnalysisConfigured = await DriveKitTripAnalysis.isConfigured()

This method returns true if it is well configured.

Vehicle

To obtain a more precise analysis on driving behavior, it's recommended to configure the vehicle used by the driver. You can do this by calling the following method:

import { TripVehicle } from 'drivekittripanalysisbridge'

tripVehicle = new TripVehicle(1, 1, 150.0, 1400.0, 2, 4.5, 0)
DriveKitTripAnalysis.setVehicle(tripVehicle)

A detailed description of vehicle parameter is available here.

Trip

You can start a trip by calling the following method:

DriveKitTripAnalysis.startTrip()

You can stop a trip by calling the following method. The trip will be stopped instantly:

DriveKitTripAnalysis.stopTrip()

If you want to cancel a trip, you can call this method:

DriveKitTripAnalysis.cancelTrip()

SDK recorder state

Two methods are available to determine SDK state.

isTripRunning = await DriveKitTripAnalysis.isTripRunning()

This method returns false if the SDK is in inactive state, and no trip is currently running.

If you want a more detailed state of the SDK, you can call the following method:

recorderState = await DriveKitTripAnalysis.getRecorderState()

This method returns the state of the SDK:

• inactive: No trip is running.
• starting: The auto start mode detects a movement of the user and checks if it's a vehicled trip.
• running: The trip has been confirmed by the speed of the movement.
• stopping: The SDK is in this state when a potential trip end is detected. If the trip continues, the SDK goes back in running state. The duration of the stopping state can be configured.
• sending: The trip is finished and is being sent to DriveQuant's server. When the SDK have the response from the server, the state becomes inactive waiting for the next trip.

Repost

Trip Analysis SDK have a repost mechanism, in most cases, when a trip is finished is sent to DriveQuant's server to be analyzed and once it's done, the result of the analysis is sent back to the SDK. In some case, the trip can't be sent to the server (no network for example). In this case, the SDK will save the trip data locally, to send it later. A retry will be attempted when the next trip will start.

If you want to check if there is locally saved trips and if they can be sent to the server, you can call the following method:

DriveKitTripAnalysis.checkTripToRepost()

Reset

If you need to reset Trip analysis configuration (user logout for example), you can call the following method:

DriveKitTripAnalysis.reset()

All data saved locally by Trip Analysis SDK will be erased and default configuration will be restored.

Auto start

The automatic mode detects vehicle movements and triggers the trip analysis without driver intervention while the application is in background. The analysis is stopped automatically at the end of the trip. This feature is recommended to avoid driver distraction and phone handling while driving. The automatic mode has been optimized to limit the battery drain.

To enable automatic trip detection mode, call the following method:

DriveKitTripAnalysis.activateAutostart(true)

To disable automatic trip detection call the same method with parameter enable set to false.

DriveKitTripAnalysis.activateAutostart(false)

Beacon usage

The automatic trip detection feature is compliant with iBeacon Bluetooth beacons. A beacon is a Bluetooth low energy (BLE) device that broadcasts a universally unique identifier. This signal can be detected by the SDK and used to trigger the trip analysis. In addition, the beacon is a smart and cost-effective solution for identifying the vehicle in which the driver is travelling. The DriveKit SDK is fully compatible with the Apple iBeacon™ standard.

You can add beacon identifiers to Trip Analysis SDK by calling the following method:

import { BeaconData } from 'drivekittripanalysisbridge'

beacons = [new BeaconData("beacon 1", 1, 1), new BeaconData("beacon 2", 2, 2), new BeaconData("beacon 3", 3, 3)]
DriveKitTripAnalysis.setBeacons(beacons)

A detailed description of Beacon class is available here.

To avoid the recording of unwanted trips (trips performed outside the vehicle where the beacon is placed), it is possible to automatically cancel the trip if the beacon is not "seen" several times during the trip. Generally, a trip will be cancelled in less than 6 minutes if the beacon is not in the vehicle.

By default, this setting is disabled, but you can enable it by calling the following method:

DriveKitTripAnalysis.setBeaconRequired(true)

To disable this setting, call the same method with the parameter set to false.

DriveKitTripAnalysis.setBeaconRequired(false)

Bluetooth usage

You can retrieve all Bluetooth devices paired to the smartphone by calling the following method:

availableBluetoothDevices = await DriveKitTripAnalysis.getAvailableBluetoothDevices()

You can add Bluetooth devices to Trip Analysis SDK by calling the following method:

import { BluetoothData } from 'drivekittripanalysisbridge'

devices = [new BluetoothData("name1", "macaddress1"), new BluetoothData("name2", "macaddress2"), new BluetoothData("name3", "macaddress3")]
DriveKitTripAnalysis.setBluetoothDevices(devices)

A detailed description of BluetoothData class is available here.

Custom stop timeout

A trip being analyzed is automatically stopped after a period of inactivity (which begins when the vehicle has stopped). The DriveQuant SDK allows to set the end-of-trip duration.

By default, the trip analysis is stopped after 240 seconds. This value can be tuned according to your need and you can choose any integer values between 120 and 480 seconds by calling the following method:

DriveKitTripAnalysis.setStopTimeOut(180)

Sharing data during the trip

The Trip Analysis SDK records the trip locally while it is in progress. The data are recorded with a period of one point per second. At the end of the trip, the SDK requests the driving analysis service and then retrieves the driving indicators.

In addition to this feature, the SDK is also able to share data with the server before the journey is completed. The data is transmitted at a lower frequency with a time interval of one point per minute.

The system for sharing information during the trip can be used in a vehicle fleet management system. This feature requires access to specific APIs. For more information, contact DriveQuant.

Sharing information with the server allows you to store the trip data even if it's been interrupted and the data post could not be performed at the end of the trip. This can happen in very rare cases such as the destruction of the mobile phone for instance.

By default, this setting is disabled but you can enable it by calling the following method:

DriveKitTripAnalysis.enableSharePosition(true)

To disable this setting, call the same method with the parameter set to false.

DriveKitTripAnalysis.enableSharePosition(false)