🚀Quick start

In this part, we will take you through the required basic steps to detect your first trips using DriveKit.

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+

• A DriveKit API key. If you don't have an API key, please contact us.

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

You can also clone the following repository, configure the required credentials then simply run the quickstart app!

Set up your project

The DriveKit SDK is available on CocoaPods public repository.

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

target 'DriveKit Quickstart' do
   pod 'DriveKitTripAnalysis'
end

then run pod install

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

In some cases you may want to manually initialize the SDK. To do this you have to disable the automatic initialization. Learn more in the Advanced configurations part.

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)

• Enable Background fetch (to periodically check for changes related to the status of authorizations, sensors, as well as user disconnection. See more info here)

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:

Info.plist

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>To enable automatic trip detection and driving analysis without having to manipulate your phone, select the option "Always allow". Good road...</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>To automatically detect and analyze your trips, the application needs access to your position at all times.</string>
<key>NSMotionUsageDescription</key>
<string>This application needs to use motion data to detect transportation mode</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>The application needs to use bluetooth in order to retrieve beacon battery level</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>The application needs to use bluetooth in order to retrieve beacon battery level</string>

These values can be localized (see our English file for example).

Configure background task ID

DriveKit periodically checks for changes related to the status of authorizations, sensors as well as user disconnection. This information is included in the diagnostic log file and shared with the DriveQuant platform. To be more accurate, this feature needs to have background fetch capability and a background task id declared in your Info.plist file. You must add the following line in Info.plist file:

Info.plist

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
	<string>com.drivequant.diagnosis.app.refresh</string>
</array>

In the case you already have a background refresh task, as iOS allow only one scheduled background fetch task, you will need to reuse your existing BGAppRefreshTask to call the following function:

DKSDKDiagnosis.shared.enqueueDiagnosisOperation(source: .backgroundFetch) { success in
    //task.setTaskCompleted(success: success)
}

In this case, don’t add the new “Permitted background task scheduler identifier” to your Info.plist.

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:

DriveKit

func setApiKey(key: String)

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:

DriveKit

func setUserId(userId: String)

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.

We recommend never using an email address or phone number to define the unique user ID. It is recommended that you set up a unique, universal and anonymous user ID. For example, you can generate a globally unique identifier (GUID) for each of your users.

DriveKit SDK will not work until you set the API key and the userId.

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:

DriveKitTripAnalysis

func activateAutoStart(enable: Bool)

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:

Podfile

target 'DriveKit Quickstart' do
   pod 'DriveKitTripAnalysis'
   pod 'DriveKitPermissionsUtilsUI'
end

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:

DriveKitPermissionsUtilsUI.shared.showPermissionViews([.location, .activity], parentViewController: self) {
    // Code called when requested permissions are properly 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:

• Configure the Core and TripAnalysis modules with advanced settings. For example, alert the user once a trip has been analyzed by the DriveQuant servers by displaying a notification, activate the crash detection, etc.
• Display trip-related data: provide a trip list, a timeline of driver’s score, present the user's driving habits, etc. by integrating the Driver Data module.
• Associate each trip to a vehicle that you can configure with the Vehicle module.
• Improve user retention by organizing challenges, display ranking with the community, show which badges the driver earned, etc.