Requirements

DriveKit is developed with the Swift 5 language and is compatible with iOS 13.0 and later versions.

The DriveKit Demo App integrates all components of the DriveKit SDK and you can refer to the code before installing the Trip Analysis component in your mobile application.

In order to understand how the smartphone telematics SDK works and how it will transform your app into a powerful sensor, take the time to read the following section that explains briefly the expected behavior.

Automatic trip recording

Before integrating the Trip Analysis component into your application, it is recommended that you understand how it works. This section explains the main states of the SDK during a trip as well as the events that trigger the transitions between states.

The diagram below shows, from top to bottom:

• Events that trigger the transition from one state to another,

• Main SDK states,

• Accessible callbacks that your application can use to implement your own business logic.

Here is a brief description of the sequence of trip analysis from A to Z. Beneath the braces, the list contains all the methods that can be called at each stage of a trip's recording.

Trip Detection: the SDK does not start instantly at the beginning of the trip. There is a variable delay during which the application identifies that a trip might be in progress. If the probability is high enough, the application turns on the GPS sensor and starts to analyze the vehicle's speed.

Trip confirmation: the trip is not validated immediately. Beforehand, the SDK checks if the trip speed is consistent with that of a motor vehicle. If this is not the case, the trip will be canceled naturally and no data will be stored locally (and no data will be transmitted to the DriveQuant's server).

Trip Recording: if the trip is confirmed by the SDK, then the data are recorded locally for the entire trip.

End of Trip Detection: the SDK can determine if the trip is completed. Each time the vehicle stops, a timer starts to check whether the stop is definitive or not. Depending on your needs, it is possible to set a time delay for stopping a trip. The default timeout value is 4 minutes. You can adjust this value between 2 and 8 minutes.

Trip Analysis: once the trip has been completed, the SDKs automate the request to the trip analysis API. If the smartphone is not connected to a mobile network, the request will be retried later.

Mobile data usage

The use of the DriveQuant SDK has a minimal impact on the driver's smartphone data plan. Data consumption is a topic that users of your application may be concerned about, so we have done our best to limit the amount of data used by the SDK.

The trip data are recorded with a frequency of 1Hz and are transmitted in text format. The volume of data recorded is about 5 kb per minute of driving:

• 50 kb of data are used for the analysis of a short 10-minute trip,

• 150 kb of data are used for the analysis of a 30-minute trip,

• A 2-hour long trip uses 600 kb of data.

The average data usage for a commuter working 30 minutes from home will be in the range of 10 Mb to 12 Mb per month.

Battery consumption

The DriveKit SDK measures data from smartphone sensors while minimizing the impact on the battery. It automatically detects the start and end of a motorized trip and does not use the GPS sensor outside of the trip.

This helps to avoid draining the phone's battery and protects the user's privacy. Location data from the phone are not collected outside of the phases where the user is driving.

Manually initialize the SDK

By default, the DriveKit SDK is automatically initialized as soon as you add the TripAnalysis module to your project.

In some cases, you may want to manually initialize the SDK. To do this, you have to disable the automatic initialization by adding the key DKAutoInitEnabled associated to the Boolean value false into the Info.plist file:

<key>DKAutoInitEnabled</key>
<false/>

Then, you must call the initialization method in didFinishLaunchingWithOptions method of your AppDelegate.

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

Check your configuration

You can check if DriveKit is well configured with the following method:

func isConfigured() -> Bool

This method returns true if these three conditions are met:

• DriveKit Core is initialized

• an API key is set

• a userId is set

Check if user is authenticated

You can check if the user is connected by calling the following method:

func isUserConnected() -> Bool

This method returns true if the user is authenticated to DriveKit.

Logging

DriveKit comes with a logging feature that is enabled by default. This feature allows you to quickly identify the cause of a problem. We recommend leaving the log enabled as it does not consume memory space and is useful in the support phase. However, if you don't want to use it, it can be disabled.

Disable logging by calling the following method:

func disableLogging(showInConsole: Bool = true)

To activate logging, call the following method:

func enableLogging(showInConsole: Bool = true)

Listen for permissions and sensors status changes

If the user disables the sensors or revokes permissions, the application would not be able to detect and record a trip. To avoid this, the SDK identifies important sensor state and permission changes.

These events are shared and you can use them in your application to inform the user via a visual alert or by displaying a notification.

DKDeviceConfigurationDelegate

DKDeviceConfigurationDelegate is a protocol used to get callbacks when device configuration changes are detected:

protocol DKDeviceConfigurationDelegate: AnyObject {
    func deviceConfigurationDidChange(event: DKDeviceConfigurationEvent)
}

Add a delegate

func addDeviceConfigurationDelegate(_ delegate: DKDeviceConfigurationDelegate)

Remove a delegate

To remove a specific delegate, call the following method:

func removeDeviceConfigurationDelegate(_ delegate: DKDeviceConfigurationDelegate)

Remove all delegates

To remove all delegates, call the following method:

func removeAllDeviceConfigurationDelegates()

DKDeviceConfigurationEvent

DKDeviceConfigurationEvent is a class describing a device configuration event.

class DKDeviceConfigurationEvent {
    let type: DKDeviceConfigurationEventType
    let isValid: Bool
}

DKDeviceConfigurationEventType

public enum DKDeviceConfigurationEventType {
    case activityPermission
    case locationPermission
    case bluetoothPermission
    case notificationPermission
    case lowPowerMode
    case locationSensor
    case bluetoothSensor
}

Possible types are:

The DriveKit SDK will run optimally if the isValid value of each event is true. The table below explains the impact of a status that is not true.

Get user’s information

To get user’s information (first name, last name and pseudo), call the getUserInfo method. It will retrieve and save these data locally:

DriveKit.shared.getUserInfo(synchronizationType: .defaultSync) { status, userInfo in
    if status == .success {
        // Get user's names in userInfo object.
    }
}

Update user’s information

You can add information to a user's account such as first name, last name and pseudo. These details are optional and you can choose to make the user's account anonymous. To update the user's information, you must call the updateUserInfo method:

DriveKit.shared.updateUserInfo(pseudo: "New_pseudo") { success in
    if success {
        // The pseudo has been successfully updated.
    }
}

Or to update all information:

DriveKit.shared.updateUserInfo(firstname: "New_firstname", lastname: "New_lastname", pseudo: "New_pseudo") { success in
    if success {
        // The firstname, lastname and pseudo have been successfully updated.
    }
}

Update UserId

It is possible to update the userId by calling the following method:

func updateUserId(userId: String)

Account deletion

You can delete a driver's account in DriveKit. This action deletes all the data related to the account.

The deletion can be done instantly or with delay.

• In the first case, when the method is called, the account is instantly deleted.

• In the second case, the driver has 30 days to log back into the application and reactivate his account.

To delete a driver's account, use the following method:

func deleteAccount(instantDeletion: Bool = false)

instantDeletion can have 2 values:

• false : Default value, allows the user to recover the deleted account by logging-in again with the same credentials. Users have 30 days starting from the day when the account was deleted.

• true : Allow to delete an account instantly. The account and all the related data will be immediately deleted and no rollback is possible.

Retrieving the installation identifier

The installation identifier (installationId) is not a unique device identifier. It is used to identify an app installation that includes the DriveKit SDK, linked to a specific account on a particular device.

The installationId is generated based on the following attributes:

• Installation date

• App

• User account

• Device type

The installationId helps determine whether a user has logged into a mobile app with the same account across multiple devices.

For a user with one account and a single device, the installationId behaves as follows:

• It remains unchanged if the user logs out and logs back in, as long as the app is not uninstalled.

• It is updated when the user uninstalls and reinstalls the app.

If a user logs into the app on several devices using the same account, each device will have a different installationId.

If the user reconnects to the app on the same device but with a different account, the installationId will be updated.

You can retrieve the installationId by calling the following computed property:

var installationId: String?

Reset

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

DriveKit.shared.reset()

All data saved locally will be erased and default configuration for every module will be restored.

This documentation is for developers. Follow the simple guideline to install our telematics SDK and access powerful insight and actionable data.

What is DriveKit?

DriveKit is a modularized software suite for creating mobile applications to engage and coach drivers.

DriveKit is composed of SDK available on both iOS and Android platforms and web services (REST API) that are designed to collect, analyze, organize, store and display driving data.

DriveKit is a 100% mobile telematics technology based on smartphone sensors to analyze vehicle trips and evaluate the influence of driving style on safety and energy consumption.

How does it work?

The DriveKit SDK transforms any iOS or Android application into a data collection solution to measure and improve driving behavior.

The SDK provides automatic detection of vehicle trips and recording of GPS data locally during the trip.

At the end of a trip, the SDK automatically requests the data analysis services embedded on the DriveQuant platform.

The DriveQuant platform contains the signal processing algorithms and databases where raw data and driving indicators resulting from the analyzes are stored.

The results of a trip analysis are usually returned to the application within seconds after the end of the trip.

The SDK contains a local database that is automatically and continuously synchronized with the DriveQuant platform database.

What are the main features included in the mobile SDK?

The DriveKit SDK is a set of independent features integrated into modules.

Some of these modules include graphical libraries with user interfaces.

The table below summarizes all the modules included in DriveKit:

Not all the DriveKit SDK modules listed in this table are strictly necessary. The key modules for transforming your application into a telematics solution are: Core and Trip Analysis.

If you plan to display the driving analysis results in your mobile application, we strongly recommend that you install the Driver Data module, which synchronizes all a driver's trips, synthesis and historical data.

What are the advantages of DriveKit?

• 100% mobile and high-performance telematics solution.

• Easy and quick integration.

• Automatic trip recording.

• Optimized battery consumption.

• Minimal use of data.

• Built-in database with automatic synchronization.

• A wide range of analytics and services.

• Plug-and-play user interfaces.

The DriveKit Demo App

Contact us

Requirements

DriveKit is developed with the Kotlin language and is compatible with Android 8.0 (API 26) and later versions.

DriveKit uses the libraries listed below. These are minimal required versions. Check that they are compatible with your app:

DriveKitListener

UpdateUserIdStatus

UpdateUserIdStatus is an enum that explains the request status after a userId has asked to be changed.

RequestError

RequestError is an enum that describes the error type of a DriveKit request.

DeleteAccountStatus

DeleteAccountStatus is an enum that describes the deletion status. It can have 3 values:

• SUCCESS: Account deleted successfully

• FAILED_TO_DELETE: Account not deleted, an error has occurred

• FORBIDDEN: Account deletion not activated for this team

DKWeather

DKWeather is an enum that describe each category of weather during a trip. It can have these values:

• UNKNOWN

• SUN

• CLOUD

• FOG

• RAIN

• SNOW

• ICE

Manually initialize the SDK

By default, the DriveKit SDK is automatically initialized as soon as you add the TripAnalysis module to your project.

In some cases, you may want to manually initialize the SDK. To do this you have to disable the automatic initialization by adding the following lines into your Manifest file:

Then, you must call the initialization methods in the onCreate method of your Application class:

Check your configuration

You can check if DriveKit is well configured with the following method:

This method returns true if these three conditions are met:

• DriveKit Core is initialized

• an API key is set

• a userId is set

Check if user is authenticated

You can check if the user is connected by calling the following method:

This method returns true if the user is authenticated to DriveKit.

Logging

DriveKit comes with a logging feature that is enabled by default. This feature allows you to quickly identify the cause of a problem. We recommend leaving the log enabled as it does not consume memory space and is useful in the support phase. However, if you don't want to use it, it can be disabled.

You can retrieve the Uri log file by calling the following method on DriveKitLog class:

Disable logging by calling the following method on DriveKit class:

To enable logging, call the following method on DriveKit class, specifying (if needed) the path of the log directory:

Listen for permissions and sensors status changes

If the user disables the sensors or revokes permissions, the application would not be able to detect and record a trip. To avoid this, the SDK identifies important sensor state and permission changes.

These events are shared when the user is logged in and you can use them in your application to inform the user via a visual alert or by displaying a notification.

DKDeviceConfigurationListener

DKDeviceConfigurationListener is the interface used to get callbacks when device configuration changes are detected:

Add a listener

Remove a listener

To remove a specific listener, call the following method:

Remove all listeners

To remove all listeners, call the following method:

DKDeviceConfigurationEvent

DKDeviceConfigurationEvent is a sealed class that describes a device configuration change event:

Possible events are:

The DriveKit SDK will run optimally if the isValid value of each event is true. The table below explains the impact of a status that is not true:

Get user’s information

To get the user's information (first name, last name and pseudo), call the getUserInfo method. This method will retrieve and save these data locally:

Update user’s information

You can add information to a user's account such as first name, last name and pseudo.

These details are optional and you can choose to make the user's account anonymous. To update the user's information, call the following method :

Update UserId

It is possible to update the userId by calling the following method:

Account deletion

You can delete a driver's account in DriveKit. This action deletes all the data related to the account.

The deletion can be done instantly or with delay.

• In the first case, when the method is called, the account is instantly deleted.

• In the second case, the driver has 30 days to log back into the application and reactivate his account.

To delete a driver's account, use the following method:

instantDeletion can have 2 values:

• false : Default value, allows the user to recover the deleted account by logging-in again with the same credentials. Users have 30 days starting from the day when the account was deleted.

• true : Allow to delete an account instantly. The account and all the related data will be immediately deleted and no rollback is possible.

Retrieving the installation identifier

The installation identifier (installationId) is not a unique device identifier. It is used to identify an app installation that includes the DriveKit SDK, linked to a specific account on a particular device.

The installationId is generated based on the following attributes:

• Installation date

• App

• User account

• Device type

The installationId helps determine whether a user has logged into a mobile app with the same account across multiple devices.

For a user with one account and a single device, the installationId behaves as follows:

• It remains unchanged if the user logs out and logs back in, as long as the app is not uninstalled.

• It is updated when the user uninstalls and reinstalls the app.

If a user logs into the app on several devices using the same account, each device will have a different installationId.

If the user reconnects to the app on the same device but with a different account, the installationId will be updated.

You can retrieve the installationId by calling the following computed property:

Reset

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

All data saved locally will be erased and default configuration for every module will be restored.

iOS guides

Get started for Swift

Android guides

Get started for Kotlin and Java

REST API

All services used by DriveKit Mobile SDK are also available through REST services. For each SDK you will find the description of web services in the REST services section.

The trip analysis API transforms GPS data collected by a smartphone or any other telematics system into actionable driver and vehicle analytics.

The API provides a broad range of indicators that depends on your subscription. DriveKit's trip analysis API provides more than 200 indicators per trip. They are organized by categories so that you can choose the ones that best suit your use case. The categories of driving indicators are listed below.

Data that represent the driver's behavior:

• Eco-driving score.

• Safety score.

• Distraction score (phone use).

• Speed limits score.

Data that measure the impact of driving behavior on the vehicle:

• Fuel consumption.

• Pollutant emissions.

• Tires and brakes wear.

Additional data describing the context of the trip:

• Departure and arrival adresses and dates.

• Average speed.

• Driving context.

• Weather.

The Trip analysis component also contains an accident detection feature that uses the smartphone's sensors to automatically detect if the vehicle has been involved in a crash. Smartphone-based accident detection allows you to:

• offer a driver assistance solution integrated into your application;

• access accurate data to speed up claims management.

DriveKitDelegate

UpdateUserIdStatus

UpdateUserIdStatus is an enum that explains the request status after a userId has asked to be changed.

RequestError

RequestError is an enum that describes the error type of a DriveKit request.

DeleteAccountStatus

DeleteAccountStatus is an enum that describes the deletion status. It can have 3 values:

• success: Account deleted successfully

• failedToDelete: Account not deleted, an error has occurred

• forbidden: Account deletion not activated for this team

DKWeather

DKWeather is an enum that describe each category of weather during a trip. It can have these values:

• unknown

• sun

• cloud

• fog

• rain

• snow

• ice

Trip autostart

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.

By default, automatic trip detection is disabled, but you can enable it by calling the following method:

DriveKitTripAnalysis.shared.activateAutoStart(enable: true)

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

DriveKitTripAnalysis.shared.activateAutoStart(enable: false)

Manually start a trip

You can start a trip by calling the following method:

DriveKitTripAnalysis.shared.startTrip()

Stop a trip

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

DriveKitTripAnalysis.shared.stopTrip()

Cancel a trip

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

DriveKitTripAnalysis.shared.cancelTrip()

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:

DriveKitTripAnalysis.shared.setVehicle(vehicle: TripVehicle?)

SDK recorder state

Two methods are available to determine SDK state.

DriveKitTripAnalysis.shared.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:

DriveKitTripAnalysis.shared.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 trip in vehicle.

• 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 has the response from the server, the state becomes inactive waiting for the next trip.

Get information about the current trip

When a trip analysis is starting, you may need some information about it, like the StartMode which triggers the trip recording, a local unique identifier of the trip that has not yet been analyzed by the DriveQuant’s servers, etc.

To retrieve information about the current trip, use the following method:

func getCurrentTripInfo() -> DKTripInfo?

DKTripInfo

Manual trip repost

Trip Analysis SDK have a repost mechanism, in most cases, when a trip is finished it 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.shared.checkTripToRepost()

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.shared.setStopTimeOut(timeOut: 180)

Manage the location sharing while driving

Thanks to the driving location sharing feature, a user can generate a link that directs to a map displaying its location while driving. Location sharing provides peace of mind to family members during a trip. This section describes the methods to manage the location-sharing link.

Check if the feature is available

If the trip sharing feature is enabled for your company, your API key carries out the feature access and a trip sharing link can be generated.

To check if the trip sharing feature is available for your API key, you can call the following code:

DriveKitTripAnalysis.shared.tripSharing.isAvailable()

Create a link

To generate a link to share trips, use the following code:

let oneHourInSeconds = 3600
DriveKitTripAnalysis.shared.tripSharing.createLink(durationInSeconds: oneHourInSeconds) { status, data in
    // Check the status and manage the data
}

The method takes a durationInSeconds parameter which indicates how long in seconds from now the sharing link will be valid.

CreateTripSharingLinkStatus

DKTripSharingLink

Retrieve a valid sharing link

To retrieve a link to share trips, use the following code:

DriveKitTripAnalysis.shared.tripSharing.getLink(synchronizationType: .defaultSync) { status, data in
    // Check the status and manage the data
}

The method takes a synchronizationType parameter. It will retrieve locally stored data if the value is .cache, otherwise with the .defaultSync value it will call the DriveQuant’s servers.

GetTripSharingLinkStatus

Revoke a trip sharing link

To revoke a trip sharing link, use the following code:

DriveKitTripAnalysis.shared.tripSharing.revokeLink { status in
    // Check the status
}

RevokeTripSharingLinkStatus

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.

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.shared.enableSharePosition(enable: true)

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

DriveKitTripAnalysis.shared.enableSharePosition(enable: false)

Here is the list of data shared every minute by the SDK:

• Date of trip start.

• Duration of the trip in seconds.

• Distance traveled in km.

• Longitude of the current location.

• Latitude of the current location.

• Smartphone battery level.

• Start-Mode for trip recording: manual, GPS-based or beacon-based.

• Beacon parameters: uuid, major, minor.

Access the trip trigger events

Why use trip triggers?

DriveKit's automatic start mode detects a trip and launches its recording immediately. This operating mode may not be appropriate for all use cases.

Your application may require other information or business logic before enabling the trip recording. For example, it may be appropriate to check that:

• A connected device is near to the smartphone.

• The trip recording is acceptable in a given time slot.

In this case, you may want to subscribe to the events that are indicative of the trip start but not necessarily launch the GPS sensor and the trip analysis.

This is why DriveKit allows you to subscribe to trigger events that indicate that a trip has probably started.

How does it work?

By default, this feature is disabled.

To enable this feature, DriveKit Trip Analysis should not be configured in automatic mode but in manual mode.

If DriveKit Trip Analysis is set to automatic mode, the trip will be recorded.

If DriveKit Trip Analysis is set to manual mode and you follow the instructions below, you will be able to listen for trip start trigger events but the trip analysis will not be started automatically.

To listen to trigger events that indicate a start of trip, even if the autostart is disabled, you can call the following method:

DriveKitTripAnalysis.shared.monitorPotentialTripStart = true

The potentialTripStart() method can return all StartMode values ; except MANUAL. Indeed, a trip manually started is considered as confirmed.

Get the arrival location of the last trip

This function returns the location of the end of the last trip recorded by the user.

The location is defined by GPS coordinates (latitude and longitude), along with the end date of the last trip and an accuracy indicator for the GPS reading.

You can use the end-of-trip coordinate for a variety of purposes, for example:

• help the user find his vehicle

• alert the customer that the user has reached a specific destination

• create a region monitoring (also known as geofencing) to locate the vehicle

To retrieve the location at which the last recorded trip ended, use the following method:

func getLastTripLocation() -> DKTripLocation?

DKTripLocation

DKCoordinateAccuracy

For ease of use, this function provides a position accuracy indicator with a 3-level scale.

Configure Capabilities

1. Go to the Capabilities tab of your target settings.

2. Turn on Background Modes and enable Location updates.

Configure permissions

As DriveKit requires a user's location and motion data, it is required to get permissions from the user.

When the application requests permission for background locations or motion activities, a message will be shown to the user. You must configure this message by changing the value for the following keys in Info.plist

• NSLocationWhenInUseUsageDescription

• NSLocationAlwaysAndWhenInUseUsageDescription

• NSMotionUsageDescription

Ask for location permission

Since iOS 13 and DriveKit SDK 1.1.3, location permission must be requested in two steps because the "Always Allow" option is no longer available in standard iOS location permission alert. You must first request when in use authorization (locationManager.requestWhenInUseAuthorization()) and then ask the user to choose "Always Allow" option in the app settings and redirect user to the app settings page.

To ask for the location permission in a proper way, DriveKit provides the following function:

DKDiagnosisHelper.shared.requestPermission(.location)

Motion and Fitness permission

Therefore, if you install DriveKit in your application, a permission request will be displayed to ask for the user's consent.

If you do not want to use this feature and want to control the user experience related to the Motion and Fitness permission request, it can be disabled.

To deactivate the Motion and Fitness permission request, call:

DriveKitTripAnalysis.shared.activateActivityRecording(false)

Prerequisites

To complete this quickstart, make sure that your development environment meets the following requirements:

• Android Studio (latest version)

• An Android 8.0+ device with Play Services

• Your Android app must target API level 26 or higher.

Follow the steps described below in your app in order to quickly integrate the DriveKit SDK:

Set up your project

The DriveKit SDK is available on the DriveQuant Maven repository.

To access modules in the repository, add the following lines in your Gradle settings appropriate file, according to the structure of your app:

Add the TripAnalysis module to your project

To add the Trip Analysis module to your app, add the following line to your dependencies in your appropriate application build Gradle file:

By adding the TripAnalysis module, it will also add the DriveKit Core module and automatically initialize the DriveKit SDK.

Configure your backup app's rules

DriveKit periodically checks for changes related to the status of permissions, sensors, as well as user disconnection. This information is included in the diagnosis log file and shared with the DriveQuant platform.

To be more accurate and capture application uninstall events, you need to allow your app to backup data.

To do this, set the allowBackup attribute to true in your Manifest project app file as shown in the following example:

Set the API key

Once you've stored your API key in a secure way in your app, configure DriveKit by calling the following method:

Set a user id

Each driver must be identified with a unique identifier. Once you have this identifier and you are ready to analyze trips, configure DriveKit by calling the following method:

You can call setApiKey() and setUserId() methods anywhere in the code. DriveKit will save the value locally. If the app is killed and relaunched, DriveKit will be reconfigured automatically.

Enable the autostart

The automatic mode detects vehicle movements and triggers the trip analysis without driver intervention even if 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.

By default, automatic trip detection is disabled, but you can enable it by calling the following method with the activate parameter to true:

Runtime permissions

DriveKit requires some runtime permissions to be granted by the user.

To display a simple and intuitive onboarding for the user to grant these runtime permissions, add the dependency for the PermissionsUtils graphical module in your appropriate application build Gradle file:

Then, call the following code in your project:

Congratulations! You now have an app that will automatically detects every trip you will make.

What's next?

Once your first trips are recorded, fine-tune the DriveKit SDK configuration to fit your needs:

Prerequisites

To complete this quickstart, make sure that your development environment meets the following requirements:

• Xcode (latest version)

• An iPhone device, running on iOS 13.0+

Follow the steps described below in your app in order to quickly integrate the DriveKit SDK:

Set up your project

The DriveKit SDK is available on CocoaPods public repository.

To add TripAnalysis module, add the following line to your Podfile:

then run pod install

By adding the TripAnalysis module, it will also add the DriveKit Core module and automatically initialize the DriveKit SDK.

Configure Capabilities

• Go to the Capabilities tab of your target settings.

• Turn on Background Modes

• Enable Location updates (to be able to receive location updates in the background)

Configure permissions

As DriveKit requires a user's location and motion data, it is required to get permissions from the user.

When the application requests permission for background locations or motion activities, usage description messages will be shown to the user. Since DriveKit imports CoreBluetooth framework, we strongly recommend you to also include Bluetooth usage description message. You must configure these messages by adding the following lines in the Info.plist file:

Configure background task ID

Set the API key

Once you've stored your API key in a secure way in your app, configure DriveKit by calling the following method:

Identify the user

Each driver must be identified with a unique identifier. Once you have this identifier and you are ready to analyze trips, configure DriveKit by calling the following method:

You can call setApiKey and setUserId methods anywhere in the code. DriveKit will save the value locally. If the app is killed and relaunched, DriveKit will be reconfigured automatically.

Enable the autostart

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 optimised to limit the battery drain.

By default, automatic trip detection is disabled, but you can enable it by calling the following method with the enable parameter to true:

Asking for permissions

To display a simple and intuitive onboarding for the user to grant these runtime permissions, add the dependency for the PermissionUtils graphical module in your Podfile:

then run pod install

The method below helps you to configure the required permission requests and the order in which they are displayed. You will be notified when the requested permissions are successfully granted:

Congratulations! You now have an app that will automatically detect every trip you will make.

What's next?

Once your first trips are recorded, fine-tune the DriveKit SDK configuration to fit your needs:

1 - Check major changes

It is necessary to read this documentation before modifying any code in your project.

2 - Targeting Android 14 in your project

To make your app fully compatible with Android 14, update the targetSdkVersion and compileSdkVersion to 34 in your project app.

3 - Apply changes ("All Apps" and "Apps targeting Android 14")

It's now time to update your code once the previous steps are taken into account.

DriveQuant recommends to specifically pay attention about these topics that can lead to a runtime crash:

4 - Update the DriveKit SDK

After you have checked that your project is working properly and updated the targetSdkVersion and compileSdkVersion, you need to update the DriveKit SDK.

• DriveKit internal modules that support Android 14 are versions 1.35 and above.

• DriveKit UI modules that support Android 14 are versions 1.39 and above.

5 - Tests 🚗

If you experience any problems with DriveKit, please contact us.

Principle

Crash detection features, included into the DriveKit Trip Analysis component, is able to collect and analyse smartphone sensors data to automatically detect when a car accident occurs.

DriveKit Trip Analysis analyzes signals from the GPS sensor and also from the motion sensors (accelerometer, gyrometer and magnetometer).

This feature is enabled if the following conditions are fulfilled:

• Your API key has the access rights to use this service;

• You have enabled the feature by following the instructions described in this section;

• A trip has been detected and is being analysed.

• The smartphone's sensors are functional.

• The SDK is able to check the status of the required sensors.

The crash detection steps are:

1. A trip is detected automatically or started manually and the trip recording starts.

2. The crash feature detects a potential collision based on motion sensors.

3. The GPS and motion data are pushed to the backend analysis services in charge of the signal processing and crash confirmation.

4. The SDK receives a crash analysis service response with a status.

5. If the crash is confirmed, the Trip analysis component can display a survey to ask the driver whether he needs assistance. This is an optional feature.

Enable crash detection

If the crash detection configuration is enabled for your company, your API key carries out the feature access and the crash detection will be enabled accordingly.

However, you can deactivate and reactivate the function if necessary using a dedicated setting.

A method is available in DriveKitTripAnalysis to enable or disable the feature:

Verify that the feature is available

It is possible to check if the crash detection is available for your configuration by checking the following property:

This property returns true if:

• the required smartphone sensors are available and up and running;

• your API key is allowed to use the feature;

Configure crash detection feedback

Trip Analysis offers a mechanism to ask the user for feedback when an accident is confirmed by the crash analysis service. Crash confirmation can be used to trigger a notification or display a screen which asks the driver to confirm the accident and whether assistance is required.

To disable the crash detection feedback, call the following method:

Listening to Crash events

TripListener protocol provides two callbacks for crash events:

To receive these callbacks, the smartphone must be connected to a mobile network and the accident detection feature must be enabled for your organisation's API key.

The TripListener protocol provides useful information and events about trips analyzed by DriveKit.

For example, you can be informed when a trip analysis has started, finished, canceled, when a crash is detected, etc.

Add a TripListener

You can remove a specific listener using the following method:

To remove all TripListeners objects:

TripListener interface includes several methods to implement:

Get the trip response status (Deprecated)

Once the DriveQuant servers has analyzed a trip, the tripFinished() callback is triggered with the data in the PostGenericResponse object.

It can be useful to check the trip response status in order to check for example if the trip is valid or not with detailed information.

To do this, call the following method:

dataExtractionRules property merge issue

If an error message appeared when building your app is something like:

Error: Attribute application@dataExtractionRules value=(@xml/data_extraction_rules) from AndroidManifest.xml:12:9-65 is also present at [com.drivequant.drivekit:drivekit-core:x.x.x] AndroidManifest.xml:13:9-56 value=(@xml/backup_rules). Suggestion: add 'tools:replace="android:dataExtractionRules"' to element at AndroidManifest.xml:9:5-31:19 to override.

It's a backup rules merging issue with DriveKit SDK rules and your app and/or another external library you use.

To resolve this, update your AndroidManifest.xml file:

<application
        android:dataExtractionRules="@xml/merged_data_extraction_rules"
        tools:replace="android:dataExtractionRules"
/>        

Then find the related backup rules of your app or the external library and create the file merged_data_extraction_rules.xml in the src/main/res/xmlfolder:

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <!-- Exclude rules of your app and/or the external libraries  -->
    <cloud-backup>
        <exclude domain="sharedpref" path="DriveKitPreferences.xml" />
        <exclude domain="sharedpref" path="DriveKitEncryptedPreferences.xml" />
        <exclude domain="sharedpref" path="DriveKitBackupPrefs.xml" />
        <include domain="sharedpref" path="DriveKitBackup.xml" />
    </cloud-backup>
    <device-transfer>
        <exclude domain="sharedpref" path="DriveKitPreferences.xml" />
        <exclude domain="sharedpref" path="DriveKitEncryptedPreferences.xml" />
        <exclude domain="sharedpref" path="DriveKitBackupPrefs.xml" />
        <include domain="sharedpref" path="DriveKitBackup.xml" />
    </device-transfer>
</data-extraction-rules>

fullBackupContent property merge issue

If an error message appeared when building your app is something like:

Error: Attribute application@fullBackupContent value=(@xml/app_backup_exclusion) from [com.anotherSdk.library:xxx:x.y.z] AndroidManifest.xml:22:18-76 is also present at [com.drivequant.drivekit:drivekit-core:x.x.x] AndroidManifest.xml:11:9-69 value=(@xml/backup_rules_pre_android_12). Suggestion: add 'tools:replace="android:fullBackupContent"' to element at AndroidManifest.xml:42:3-72:17 to override.

It's a backup rules merging issue with DriveKit SDK rules and your app and/or another external library you use.

To resolve this, update your AndroidManifest.xml file:

<application
        android:fullBackupContent="@xml/merged_backup_rules"
        tools:replace="android:fullBackupContent" 
        (…)
/>

Then find the related backup rules of your app or the external library and create the file merged_backup_rules.xml in the src/main/res/xmlfolder:

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
	<!-- Exclude rules of your app and/or the external libraries  -->

	<exclude domain="sharedpref" path="DriveKitPreferences.xml" />
	<exclude domain="sharedpref" path="DriveKitEncryptedPreferences.xml" />
	<exclude domain="sharedpref" path="DriveKitBackupPrefs.xml" />
	<include domain="sharedpref" path="DriveKitBackup.xml" />
</data-extraction-rules>

<application
        android:dataExtractionRules="@xml/merged_data_extraction_rules"
        android:fullBackupContent="@xml/merged_backup_rules"
        tools:replace="android:dataExtractionRules, android:fullBackupContent"
        (…)
/>

BackupAgent merge issue

If an error message appeared when building your app looks like:

Copy

Manifest merger failed : Attribute application@backupAgent value=(com.yourApp.yourClass) from AndroidManifest.xml:9:9-47
	is also present at [:Core] AndroidManifest.xml:11:9-86 value=(com.drivequant.drivekit.core.backup.DriveKitBackupAgent).
	Suggestion: add 'tools:replace="android:backupAgent"' to <application> element at AndroidManifest.xml:7:5-42:19 to override.

It's because DriveKit SDK is using the BackupAgent to restore some user information when the user has reinstalled the app.

DriveKit is providing two ways to handle the error:

Way 1 - Inherit from DriveKitBackupAgent

The easiest way is to make your BackupAgent class inherits our DriveKitBackupAgent class.

Way 2 - Call DriveKit backup methods

If you cannot inherit from DriveKitBackupAgent class, e.g. when you already inherits from another class, you can still:

1. Add tools:replace="android:backupAgent in your Manifest as suggested in the error message.

2. Call DriveKitBackupAgent.onCreate(BackupAgentHelper) in your overriden onCreate() method

3. Call DriveKitBackupAgent.onRestoreFinished(BackupAgentHelper) in your overriden onRestoreFinished() method

Location Permission

It is required to ask the user for location permission. Find below an example of how to ask location permission:

fun checkLocationPermission(requestCode: Int) {
    val permissionFineLocationApproved = ActivityCompat.checkSelfPermission(this,
        Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED

    if (permissionFineLocationApproved) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            val backgroundLocationPermissionApproved = ActivityCompat.checkSelfPermission(
                this, Manifest.permission.ACCESS_BACKGROUND_LOCATION
            ) == PackageManager.PERMISSION_GRANTED
            if (!backgroundLocationPermissionApproved) {
                ActivityCompat.requestPermissions(this,
                    arrayOf(Manifest.permission.ACCESS_BACKGROUND_LOCATION),
                    requestCode)
            }
        }
    } else {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            ActivityCompat.requestPermissions(this,
                arrayOf(
                    Manifest.permission.ACCESS_FINE_LOCATION,
                    Manifest.permission.ACCESS_BACKGROUND_LOCATION),
                requestCode)
        } else {
            ActivityCompat.requestPermissions(this,
                arrayOf(Manifest.permission.ACCESS_FINE_LOCATION),
                requestCode)
        }
    }
}

private void checkLocationPermission(int requestCode) {
        boolean permissionFineLocationApproved = ActivityCompat.checkSelfPermission(this,
                Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED;

        if (permissionFineLocationApproved) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                boolean backgroundLocationPermissionApproved = ActivityCompat.checkSelfPermission(
                        this, Manifest.permission.ACCESS_BACKGROUND_LOCATION
                ) == PackageManager.PERMISSION_GRANTED;
                if (!backgroundLocationPermissionApproved) {
                    ActivityCompat.requestPermissions(this,
                            new String[] { Manifest.permission.ACCESS_BACKGROUND_LOCATION },
                            requestCode);
                }
            }
        } else {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                ActivityCompat.requestPermissions(this,
                        new String[] {
                                Manifest.permission.ACCESS_FINE_LOCATION,
                                Manifest.permission.ACCESS_BACKGROUND_LOCATION },
                        requestCode);
            } else {
                ActivityCompat.requestPermissions(this,
                        new String[] { Manifest.permission.ACCESS_FINE_LOCATION },
                        requestCode);
            }
        }
    }

Activity Recognition Permission

For device running Android 10 and above, it's required to ask the user for activity recognition permission. Find below an example of how to ask the permission:

fun checkActivityRecognitionPermission(requestCode: Int) {
    var isActivityRecognitionAuthorize = true
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        isActivityRecognitionAuthorize = ContextCompat.checkSelfPermission(this,
            Manifest.permission.ACTIVITY_RECOGNITION) == PackageManager.PERMISSION_GRANTED
    } else {
        // call DriveKitTripAnalysis.activateAutoStart(true)
    }
    if (!isActivityRecognitionAuthorize && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        if (ActivityCompat.shouldShowRequestPermissionRationale(this,
                Manifest.permission.ACTIVITY_RECOGNITION)) {
            // Display a message to explain why the permission is necessary
        } else {
            ActivityCompat.requestPermissions(this,
                arrayOf(Manifest.permission.ACTIVITY_RECOGNITION),
                requestCode)
        }
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    // call DriveKitTripAnalysis.activateAutoStart(true)
}

private void checkActivityRecognitionPermission(int requestCode) {
    boolean isActivityRecognitionAuthorize = true;
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        isActivityRecognitionAuthorize = ActivityCompat.checkSelfPermission(this,
                Manifest.permission.ACTIVITY_RECOGNITION) == PackageManager.PERMISSION_GRANTED;
    } else {
        // call DriveKitTripAnalysis.INSTANCE.activateAutoStart(true)
    }
    if (!isActivityRecognitionAuthorize && Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        if (ActivityCompat.shouldShowRequestPermissionRationale(this,
                Manifest.permission.ACTIVITY_RECOGNITION)) {
            // Display a message to explain why the permission is necessary
        } else {
            ActivityCompat.requestPermissions(this,
                    new String[] { Manifest.permission.ACTIVITY_RECOGNITION },
                    requestCode);
        }
    }
}

@Override
public void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    // call DriveKitTripAnalysis.INSTANCE.activateAutoStart(true)
}

Battery optimization

It is required to ask the user to disable battery optimization for your app. Without battery optimization disabled, Trip Analysis SDK will not work properly.

Call the following code after explaining to the user why disabling battery optimization is required:

fun checkBatteryOptimization() {
    val packageName = this.packageName
    val pm = activity.getSystemService(Context.POWER_SERVICE) as PowerManager
    if (!pm.isIgnoringBatteryOptimizations(packageName)) {
        val intent = Intent()
        intent.action = Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
        intent.data = Uri.parse("package:$packageName")
        this.startActivity(intent)
    }
}

void checkBatteryOptimization() {
    Intent intent = new Intent();
    String packageName = getPackageName();
    PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
    if (pm != null && !pm.isIgnoringBatteryOptimizations(packageName)) {
        intent.setAction(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS);
        intent.setData(Uri.parse("package:" + packageName));
        startActivity(intent);
    }
}

Nearby Devices Permission

fun checkNearbyDevicesPermission(activity: Activity, requestCode : Int) {
    val isNearbyDevicesPermissionAuthorized = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        ContextCompat.checkSelfPermission(
            activity, Manifest.permission.BLUETOOTH_SCAN
        ) == PackageManager.PERMISSION_GRANTED
                && ContextCompat.checkSelfPermission(
            activity, Manifest.permission.BLUETOOTH_CONNECT
        ) == PackageManager.PERMISSION_GRANTED
    } else {
        true
    }

    if (!isNearbyDevicesPermissionAuthorized && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        val shouldShowRationaleScan = shouldShowRequestPermissionRationale(activity, Manifest.permission.BLUETOOTH_SCAN)
        val shouldShowRationaleConnect = shouldShowRequestPermissionRationale(activity, Manifest.permission.BLUETOOTH_CONNECT)
        if (!shouldShowRationaleScan || !shouldShowRationaleConnect) {
            // Display a message to explain why the permission is necessary 
        } else {
            requestPermissions(activity, arrayOf(Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT), requestCode)
        }        
    }
}

public void checkNearbyDevicesPermission(Activity activity, int requestCode) {
    boolean isNearbyDevicesPermissionAuthorized;
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        isNearbyDevicesPermissionAuthorized = ContextCompat.checkSelfPermission(
                activity, Manifest.permission.BLUETOOTH_SCAN
        ) == PackageManager.PERMISSION_GRANTED
                && ContextCompat.checkSelfPermission(
                activity, Manifest.permission.BLUETOOTH_CONNECT
        ) == PackageManager.PERMISSION_GRANTED;
    }  else {
        isNearbyDevicesPermissionAuthorized = true;
    }
    
    if (!isNearbyDevicesPermissionAuthorized && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        final boolean shouldShowRationaleScan = shouldShowRequestPermissionRationale(activity, Manifest.permission.BLUETOOTH_SCAN);
        final boolean shouldShowRationaleConnect = shouldShowRequestPermissionRationale(activity, Manifest.permission.BLUETOOTH_CONNECT);
        if (!shouldShowRationaleScan || !shouldShowRationaleConnect) {
            // Display a message to explain why the permission is necessary
        } else {
            requestPermissions(activity, new String[] { Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT }, requestCode);
        }
    }
}

Notification Runtime Permission

Find below an example of how to ask the Notification permission:

First, declare the permission in your Manifest app file:

<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application ...>
        ...
    </application>
</manifest>

Then request the permission on your UI:

fun checkNotificationPermission(activity: Activity, requestCode: Int) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        val isNotificationPermissionAuthorized = ContextCompat.checkSelfPermission(activity,
            Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED

        if (!isNotificationPermissionAuthorized) {
            if (ActivityCompat.shouldShowRequestPermissionRationale(activity,
                    Manifest.permission.POST_NOTIFICATIONS)) {
                // Display a message to explain why the user need to grant the permission
            } else {
                ActivityCompat.requestPermissions(activity,
                    arrayOf(Manifest.permission.POST_NOTIFICATIONS),
                    requestCode)
            }
        }
    }
}

public void checkNotificationPermission(Activity activity, int requestCode) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        boolean isNotificationPermissionAuthorized = ContextCompat.checkSelfPermission(activity, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED;
        if (!isNotificationPermissionAuthorized) {
            if (ActivityCompat.shouldShowRequestPermissionRationale(activity,
                    Manifest.permission.POST_NOTIFICATIONS)) {
                // Display a message to explain why the user need to grant the permission
            } else {
                ActivityCompat.requestPermissions(activity, new String[] { Manifest.permission.POST_NOTIFICATIONS }, requestCode);
            }
        }
    }
}

Full-screen intent permission

If the permission is not granted, the user will not receive full-screen notifications when the smartphone is locked, but instead an expanded heads-up notification on lockscreen. Find below an example of how to ask the full-screen intent permission:

First, declare the permission in your Manifest app file:

<manifest ...>
    <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT"/>
    <application ...>
        ...
    </application>
</manifest>

Then request the permission on your UI:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
    DiagnosisHelper.requestFullScreenPermission(activity)
}

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
    DiagnosisHelper.INSTANCE.requestFullScreenPermission(activity);
}

Google Play Services

Trip Analysis component requires Google Play Services Location 21.0.1 or above.

You can check if Play Services are available on the device with the following code:

fun checkGooglePlayServices() {
    val apiAvailability = GoogleApiAvailability.getInstance()
    val resultCode = apiAvailability.isGooglePlayServicesAvailable(this)
    if (resultCode != ConnectionResult.SUCCESS) {
        if (apiAvailability.isUserResolvableError(resultCode)) {
            apiAvailability.getErrorDialog(this, resultCode, 9000).show()
        }
    }
}

Principle

Bluetooth wireless technology is a common solution in modern vehicles. Most drivers know that by pairing their Bluetooth smartphone with their car stereo receiver, they will be able to make hands-free calls or to stream their music to the car audio system.

Once the smartphone's paired with the vehicle, it automatically connects to it if the vehicle is started.

Trip Analysis SDK is capable of detecting this event to start a trip analysis.

A Bluetooth device is identified by a unique MAC address and an optional name. It can be detected by the SDK and used to trigger the trip analysis.

The use of the vehicle Bluetooth detection is a simple and cost-effective solution to identify the trips made with your vehicle.

Configure a Bluetooth device

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

let devices = DriveKitTripAnalysis.shared.getAvailableBluetoothDevices()

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

DriveKitTripAnalysis.shared.setBluetoothDevices(bluetoothDevices: [BluetoothData])

Bluetooth device required

Pairing the vehicle's Bluetooth system improves the trip detection and analysis. With this feature you can decide to enable or disable the trip recording when the Bluetooth device is not connected. There are two possibilities:

1. the trip can be recorded even if the smartphone is not connected to the Bluetooth device.

2. the trip recording will be cancelled if the smartphone is not connected to the Bluetooth device.

This choice depends on your use case. In general, if you only want to record trips made with the vehicle equipped with the paired Bluetooth system, you must prefer the second choice.

To avoid trip recording when the Bluetooth device is not connected, call the following method:

DriveKitTripAnalysis.shared.setBluetoothDeviceRequired(true)

To enable trip recording regardless of the state of the Bluetooth system (connected or not connected to the smartphone), call the following method:

DriveKitTripAnalysis.shared.setBluetoothDeviceRequired(false)

Configure beacons

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.

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

DriveKitTripAnalysis.shared.setBeacons(beacons: [BeaconData])

Beacon required

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.shared.setBeaconRequired(required: true)

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

DriveKitTripAnalysis.shared.setBeaconRequired(required: false)

Filter the beacon trigger to start trip recording

In very rare cases, it may be useful to avoid trip detection using the beacon but still need to validate the trip recording only if the beacon is near the smartphone during the trip.

In this case, the beacon is used in trip validation mode but not in trip detection mode.

How does it work ?

By default, if you have configured a beacon, its detection by the SDK will start a trip analysis.

In very rare cases (e.g. beacon in a vehicle and parked in close proximity to a living area), it might be useful to avoid the SDK to start a trip when a beacon is detected to reduce smartphone battery consumption.

Please note that beacon scans checks are always performed during the trip analysis, even if the configuration is called.

To disable the ability to start a trip analysis when a beacon is detected by DriveKit, you can call the following method:

DriveKitTripAnalysis.shared.allowBeaconTripStart = false

Beacon battery level

For this functionality to work properly, the user must allow access to Bluetooth and you have to configure your project to allow background access to Bluetooth as described below.

• In your target, in the "Signing & Capabilities" tab, you need to check the "Uses Bluetooth LE accessory" box in "Background Modes":

• Ask the user for Bluetooth access authorization if it is not already granted. To do this, you can call this method:

DKDiagnosisHelper.shared.requestPermission(.bluetooth)

TripResponseStatus

TripResponseStatus indicates if the analyzed trip by the DriveQuant servers is valid or not (see status property) and provides information on the analysis result:

TripResponseInfo

TripResponseError

DKTrip

DKDeclaredTransportationMode

The user has the possibility to declare the transportation mode that was used during a trip to confirm the one detected or to change it, and to declare whether the trip was made as a passenger or as the driver.

Here is the description of the corresponding object:

DKTripRecordingStartedState

DKTripRecordingConfirmedState

DKTripRecordingCanceledState

DKTripRecordingFinishedState

StartMode

StartMode indicates how the trip is started. It is an enum with the following values:

DKTripCancelationReason

TripPoint

TripPoint is an object that contains data for each location registered by the SDK.

TripVehicle

TripVehicle is an object that contains vehicle detailed characteristics.

BeaconData

BeaconData is an object that contains beacon characteristics.

BluetoothData

BluetoothData is an object that contains the Bluetooth device characteristics.

DKCrashInfo

Crash information object have the following structure:

with the following enumeration for crash status

DKCrashFeedbackConfig

DKCrashFeedbackConfig is an object used to configure the Crash Detection feedback feature.

DKCrashFeedbackNotification

DKCrashAlert

CrashFeedbackType

CrashFeedbackSeverity

CancelTrip (Deprecated)

CancelTrip indicates how the trip was cancelled. It is an enum with the following values:

Configure the trip notification content

TripNotification is an object that contains the configuration of the foreground notification displayed during a trip recording.

To configure the trip notification in your app, call the following code: