Get started

Prerequisite

Before starting DriveKit Driver Data integration, make sure that you have initialized DriveKit.

If you use Driver Data without having initialized DriveKit, the SDK may not work properly in your application.

Integration

Get framework

To add the DriverData module to your app:

• Swift Package Manager: Add DriveKitDriverData from repository: https://github.com/DriveQuantPublic/drivekit-sdk-spm.git as dependency.

• Cocoapods: add the following pod to your Podfile:

Podfile

target 'my-target' do
  pod 'DriveKitDriverData'
end

Then, run pod install.

Initialization

If you have disabled the SDK auto-initialization, an initialization phase is required to use the feature included in the Driver Data module. In the application's AppDelegate file, import DriveKitDriverData:

import DriveKitDriverDataModule

Then, to initialize Driver Data module in your app, you must call the initialization method in didFinishLaunchingWithOptions method of your AppDelegate file.

AppDelegate.swift

import DriveKitCoreModule
import DriveKitTripAnalysisModule

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

Get driver trips

To get Driver trips, you have to call the following method:

public func getTripsOrderByDateDesc(type: SynchronizationType = .defaultSync, completionHandler: @escaping (TripSyncStatus, [DKTrip]) -> ())

SynchronizationType can have 2 values:

• defaultSync: if this value is used, the SDK will try to synchronize local trips with DriveQuant backend to get new trips or modified trips, and then return the trip list via the completionHandler.

• cache: if this value is used, no synchronization will be performed and only trips previously synchronized will be returned via the completionHandler.

TripSyncStatus in the completionHandler can have 4 values:

• noError: Synchronization has been successfully performed.

• cacheDataOnly: SynchronizationType has been set to cache.

• failedToSyncTripsCacheOnly: Synchronization has failed, only trips previously synchronized are returned.

• syncAlreadyInProgress: A synchronization is in progress, only trips previously synchronized are returned until the synchronization is finished.

The second argument in the completionHandler is the list of DKTrip objects.

Trips are returned and sorted by end date in descending order.

If train trips have been recorded by Trip Analysis SDK, they won't be returned by this method.

Example:

DriveKitDriverData.shared.getTripsOrderByDateDesc(completionHandler: { status, trips in
    // Check status and use trips data
})

Get specific trip

To get a specific trip, you have to call the following method:

public func getTrip(itinId: String, completionHandler: @escaping (TripSyncStatus, DKTrip?) -> ())

The itinId parameter is the unique identifier for a trip.

When you call this method, you will get trip data and trip safety events. If safety events are not synchronized locally for the trip, a synchronization with DriveQuant backend will be performed and then, the trip will be returned with safety events synchronized.

TripSyncStatus can have the same value as above and the value failedToSyncSafetyEvents if the safety events synchronization failed.

The second argument in the completionHandler is the requested Trip object, if exists.

Example:

DriveKitDriverData.shared.getTrip(itinId: itinId, completionHandler: { status, trip in
    // Check status and use trip data
})

Get trip road data

To get road data of the trip (latitude, longitude), you have to call the following method:

public func getRoute(itinId: String, completionHandler: @escaping (DKRoute?) -> ())

If route value in completionHandler is nil , the synchronization has failed.

Example:

DriveKitDriverData.shared.getRoute(itinId: itinId, completionHandler: { route in
    if let route = route {
        // Use route data
     } else {
        // Failed to synchronize route
     }
})

Delete a trip

To delete a trip, you have to call the following method:

 public func deleteTrip(itinId: String, completionHandler: @escaping (Bool) -> ())

The itinId parameter is the unique identifier for a trip.

Example:

DriveKitDriverData.shared.deleteTrip(itinId: self.viewModel.itinId, completionHandler: { deleteSuccessful in
    if deleteSuccessful {
        // trip successfully deleted
    } else {
        // Failed to delete trip
    }
})

Declare a trip made as passenger

When a trip is analyzed and the detected transportation mode is car, truck, or motorcycle, it is by default attributed to the driver. However, in some cases, the data may come from a passenger's smartphone.

In such cases, it is possible to indicate that the analyzed trip was recorded by an occupant of the vehicle who was not the driver. This section describes the method used to declare a trip as having been made as a passenger.

With this method, you can add a feature to your application that allows the user to declare that they were not the driver of the vehicle.

When a user declares that a trip was made as a passenger, it will not modify any scores related to the trip.

To declare a trip as a passenger with a comment, call the following code:

Swift

let itinid = "myItineraryId"
let mode = DKDriverPassengerMode.passenger
let comment = "I was the passenger"
DriveKitDriverData.shared.updateDriverPassengerMode(itinId: itinid, mode: mode, comment: comment) { status in
	switch status {
	case .success:
    	// Success, the data have been updated in the local database
	case .userNotConnected:
    	// An error occurred, the user is not yet connected.
	case .invalidTransportationMode:
    	// Error, the trip was made with an alternative transport
	case .invalidItineraryId:
    	// Error, the provided itinerary identifier does not exist or has not been made by the user
	case .commentTooLong:
    	// Error, the comment is too long
	case .failedToUpdateMode:
    	// An error occurred, for example when the user has no network.
	}
}

The method takes the following parameters:

Field	Type	Description
itinId	String	Unique trip identifier
mode	DKDriverPassengerMode	Possible value: driver or passenger.
comment	String	The user can add a comment of up to 120 characters.

The method returns a UpdateDriverPassengerModeStatus enum with the possible values:

Value	Description
success	The passenger status has been successfully updated and local trip data is also updated.
userNotConnected	The user is not yet connected to DriveKit.
invalidItineraryId	The itinerary identifier does not exist. Update is not taken into account and local trip data is not updated either.
invalidTransportationMode	The trip was made with alternative transport. Update is not taken into account and local trip data is not updated either.
commentTooLong	The comment exceeds 120 characters. Update is not taken into account and local trip data is not updated either.
failedToUpdateMode	An error has occurred, for example if the user has no network. Update is not taken into account and local trip data is not updated either.

Get driver synthesis

To get driver synthesis data, you have to call the following method:

public func getSynthesis(type: SynchronizationType = .cache, completionHandler: @escaping (SynthesisSyncStatus, DKSynthesis?) -> ())

SynchronizationType can have 2 values:

• defaultSync: if this value is used, the SDK will try to synchronize the driver synthesis data with DriveQuant backend and then return it via the completionHandler.

• cache: if this value is used, no synchronization will be performed and the data retrieved during the last synchronisation will be returned via the completionHandler.

SynthesisSyncStatus in the completionHandler can take 3 values:

• cacheDataOnly: SynchronizationType has been set to cache.

• noError: Synchronization has been successfully performed.

• failedToSyncSynthesisCacheOnly: Synchronization has failed, only data retrieved during the last synchronisation is returned.

Example:

import DriveKitDriverDataModule

DriveKitDriverData.shared.getSynthesis(type: .defaultSync) { status, synthesis in
    // Check status and use synthesis
}

public func getDriverTimelines(periods: [DKPeriod], type: SynchronizationType = .defaultSync, completionHandler: @escaping (TimelineSyncStatus, [DKDriverTimeline]?) -> Void)

periods attribute contains periods you are interested in: .week , .month and/or .year.

• defaultSync: if this value is used, the SDK will try to synchronize timelines with DriveQuant backend and then return them via the completionHandler.

• cache: if this value is used, no synchronization will be performed and the data retrieved during the last synchronisation will be returned via the completionHandler.

• cacheDataOnly: SynchronizationType has been set to cache.

• noError: Synchronization has been successfully performed.

• failedToSyncTimelineCacheOnly: Synchronization has failed, only data retrieved during the last synchronisation are returned.

• noTimelineYet: Synchronization has been successfully performed and there is currently no timeline.

import DriveKitDriverDataModule

DriveKitDriverData.shared.getTimelines(periods: [.week, .month], type: .defaultSync) { (status, timelines) in
    // Check status and use timelines
}

Get driver timelines

To get driver timelines, you have to call the following method:

public func getDriverTimelines(
    periods: [DKPeriod],
    ignoreItemsWithoutTripScored: Bool = false,
    type: SynchronizationType = .defaultSync,
    completionHandler: @escaping (TimelineSyncStatus, [DKDriverTimeline]?) -> Void
)

TimelineSyncStatus in the completionHandler can take 4 values:

• cacheDataOnly: SynchronizationType has been set to cache.

• noError: Synchronisation has been successfully performed.

• failedToSyncTimelineCacheOnly: Synchronisation has failed, only data retrieved during the last synchronisation are returned.

• noTimelineYet: Synchronisation has been successfully performed and there is currently no timeline.

The second argument in the completionHandler is a list of DKDriverTimeline object, one per period requested.

Example:

import DriveKitDriverDataModule

DriveKitDriverData.shared.getDriverTimelines(periods: [.week, .month, .year], type: .defaultSync) { (status, timelines) in
    // Check status and use timelines
}

Get driver profile

To get driver profile, you have to call the following method:

public func getDriverProfile(
   type: SynchronizationType = .defaultSync,
   completionHandler: @escaping (DKDriverProfileStatus, DKDriverProfile?) -> Void
)

SynchronizationType can have 2 values:

• defaultSync: if this value is used, the SDK will try to synchronize the driver profile with DriveQuant backend and then return it via the completionHandler.

• cache: if this value is used, no synchronisation will be performed and the data retrieved during the last synchronisation will be returned via the completionHandler.

DKDriverProfileStatus in the completionHandler can take 4 values:

• success: Synchronization type has been successfully performed.

• failedToSyncDriverProfileCacheOnly: Synchronisation has failed, only data retrieved during the last synchronisation is returned.

• noDriverProfileYet: Synchronisation has been successfully performed and there is currently no driver profile for this user.

• forbiddenAccess: Your team doesn’t have access to this data.

The second argument in the completionHandler is the DKDriverProfile object requested.

import DriveKitDriverDataModule

DriveKitDriverData.shared.getDriverProfile(type: .defaultSync) { (status, driverProfile) in
    // Check status and use driverProfile
}