ProductsUse casesDocsSupport

🚀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 with Swift Package Manager (or this one with CocoaPods), configure the required credentials and then simply run the quickstart app!

Set up your project

The DriveKit SDK is available on Swift Package Manager and on CocoaPods public repository. The recommended method for integrating the DriveKit iOS SDK and its dependencies into your application is to use Swift Package Manager (SPM).

CocoaPods support will be discontinued by the end of 2025, as CocoaPods Trunk is expected to become read-only. We strongly recommend migrating from CocoaPods to Swift Package Manager (SPM) as soon as possible.

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.

Swift Package Manager (Recommended)

Via Xcode:

  • In Xcode, add the DriveKit SDK by navigating to File > Add Package Dependencies...

  • In the prompt that appears, enter the DriveKit repository: https://github.com/DriveQuantPublic/drivekit-sdk-spm.git

  • Include DriveKitTripAnalysis in your app.

Via Package.swift:

  • To integrate DriveKit to a Swift package via a Package.swift file, you can add DriveKit to the dependencies array of your package. For more details, see the Swift Package Manager documentation.

dependencies: [
  .package(name: "DriveKit",
           url: "https://github.com/DriveQuantPublic/drivekit-sdk-spm.git",
           from: "2.0.0"),
  // ...
],

  • Then in any target that depends on a DriveKit module, add it to the dependencies array of that target:

.target(
  name: "MyTarget",
  dependencies: [
    .product(name: "DriveKitTripAnalysis", package: "DriveKit"),
    // ...
  ]
),

Cocoapods (deprecation scheduled for the end of 2025)

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

target 'MyTarget' do
   pod 'DriveKitTripAnalysis'
end

then run pod install

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:

<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:

<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:

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:

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:

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:

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:

PreviousiOSNextAdvanced configurations

Last updated

Was this helpful?