Get started

Prerequisite

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

If you use DriveKit Driver Data without having initialized DriveKit, an exception will be generated and the SDK will not work in your application.

Integration

Get module from repository

To add Driver Data module to your app, add the following line to your dependencies in your application build.gradle file:

dependencies {
    implementation 'com.drivequant.drivekit:drivekit-driver-data:$drivekit_version'
}

Replace $drivekit_version with the DriveKit version you are using in your app

Initialization

If you have disabled the SDK auto-initialization, an initialization phase is required to use the functions offered by the Driver Data component. To initialize Driver Data component in your app, you must call the initialization method in onCreate method of your application class.

DriveKitDriverData

fun initialize()

Get driver trips

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

DriveKitDriverData

fun getTripsOrderByDateDesc(listener: TripsQueryListener, type: SynchronizationType = SynchronizationType.DEFAULT)

SynchronizationType can have 2 values:

• DEFAULT: 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 return via the completionHandler.

An implementation of TripsQueryListener must be provided in order to retrieve trips.

interface TripsQueryListener {
    fun onResponse(status: TripsSyncStatus, trips: List<Trip>)
}

The status in onResponse have one of the following values:

• NO_ERROR: Synchronization has been successfully performed.

• CACHE_DATA_ONLY: SynchronizationType has been set to CACHE.

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

• SYNC_ALREADY_IN_PROGRESS : Another trip list synchronization is already in progress

The second argument of the onResponse method is a list of Trip objects.

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

Example:

DriveKitDriverData.getTripsOrderByDateDesc(object: TripsQueryListener {
                override fun onResponse(status: TripsSyncStatus, trips: List<Trip>) {
                    // Check status and trips data
                }
            }, SynchronizationType.DEFAULT)

Get specific trip

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

DriveKitDriverData

fun getTrip(itinId: String, listener: TripQueryListener)

The itinId parameter is the unique identifier for a trip.

An implementation of TripQueryListener must be provided in order to retrieve the trip.

interface TripQueryListener {
    fun onResponse(status: TripsSyncStatus, trip: 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 FAILED_TO_SYNC_SAFETY_EVENTS if the safety events synchronization failed.

The second argument of the onResponse method is the requested Trip object, if exists.

Example:

DriveKitDriverData.getTrip(itinId, object: TripQueryListener {
    override fun onResponse(status: TripsSyncStatus, trip: Trip?) {
        // 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:

DriveKitDriverData

fun getRoute(itinId: String, listener: RouteQueryListener)

An implementation of RouteQueryListener must be provided in order to retrieve the trip.

interface RouteQueryListener {
    fun onResponse(status: RouteStatus, route: Route?)
}

RouteStatus can have 2 values:

• NO_ERROR: The trip has been successfully retrieved.

• FAILED_TO_RETRIEVE_ROUTE: Route has not been synchronized. route parameter will be null.

Example:

DriveKitDriverData.getRoute(itinId, object: RouteQueryListener {
    override fun onResponse(status: RouteStatus, route: Route?) {
        // Check status and use route data
    }
})

Delete a trip

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

DriveKitDriverData

fun deleteTrip(itinId: String, listener: TripDeleteQueryListener)

The itinId parameter is the unique identifier for a trip.

Example:

DriveKitDriverData.deleteTrip(itinId, object: TripDeleteQueryListener {
    override fun onResponse(status: Boolean) {
        if (status) {
            //Trip succesfully deleted
        } else {
            // Failed to delete trip
        }
    }
})

Get driver synthesis

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

DriveKitDriverData

fun getSynthesis(
   listener: SynthesisQueryListener,
   synchronizationType: SynchronizationType)

An implementation of SynthesisQueryListener must be provided in order to retrieve synthesis data.

interface SynthesisQueryListener {
fun onResponse(synthesisStatus: SynthesisStatus, synthesis: Synthesis?)
}

SynthesisStatus in the callback can have 3 values:

• NO_ERROR: Synchronization has been successfully performed.

• CACHE_DATA_ONLY: SynchronizationType has been set to cache.

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

Example:

Kotlin

DriveKitDriverData.getSynthesis(object : SynthesisQueryListener {
    override fun onResponse(
        synthesisStatus: SynthesisStatus,
        synthesis: Synthesis?
    ) {
        // Check synthesisStatus and use synthesis data
    }
})

Java

DriveKitDriverData.INSTANCE.getSynthesis(new SynthesisQueryListener() {
            @Override
            public void onResponse(@NotNull SynthesisStatus synthesisStatus,                    @Nullable Synthesis synthesis) {
                  // Check synthesisStatus and use synthesis data
            }
        }, SynchronizationType.DEFAULT);

Get driver timelines

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

DriveKitDriverData

fun getDriverTimelines(
        periods: List<DKPeriod>,
        synchronizationType: SynchronizationType = SynchronizationType.DEFAULT,
        ignoreItemsWithoutTripScored: Boolean = false,
        callback: (timelineSyncStatus: TimelineSyncStatus, timelines: List<DKDriverTimeline>) -> Unit
)

Parameter name	Type	Description
periods	DKTimelinePeriod	Get timeline data in a specific period of time. Possible values are : WEEK, MONTH, YEAR.
synchronizationType	SynchronizationType	Define the source of the timelines data you want to retrieve. Possible values are: CACHE: No sync will be performed and the data retrieved during the last sync will be returned via the callback. DEFAULT: the SDK will try to synchronize timelines with DriveQuant backend and then return them via the callback.
ignoreItemsWithoutTripScored	Boolean	If set to true, the returned timeline data will not contain items (DKAllContextItem and DKRoadContextItem) where there are only unscored trips.

The TimelineSyncStatus enum values are:

• CACHE_DATA_ONLY: SynchronizationType has been set to CACHE.

• NO_ERROR: Sync has been successfully performed.

• FAILED_TO_SYNC_TIMELINE_CACHE_ONLY: Sync has failed, only data retrieved during the last sync are returned.

• NO_TIMELINE_YET: Sync has been successfully performed and there is currently no timeline.

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

Get driver profile

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

DriveKitDriverData

fun getDriverProfile(
    synchronizationType: SynchronizationType = SynchronizationType.DEFAULT,
    callback: (status: DKDriverProfileStatus, driverProfile: DKDriverProfile?) -> Unit
)

SynchronizationType can have 2 values:

• DEFAULT: 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 callback.

DKDriverProfileStatus in the callback can take 4 values:

• SUCCESS: Synchronization type has been successfully performed.

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

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

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

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

Example:

Kotlin

import com.drivequant.drivekit.driverdata.DriveKitDriverData

DriveKitDriverData.getDriverProfile(type: DKDriverProfileStatus.DEFAULT) { status, driverProfile ->
    // Check status and use driverProfile
}

Java

import com.drivequant.drivekit.core.SynchronizationType;
import com.drivequant.drivekit.driverdata.DriveKitDriverData;

DriveKitDriverData.INSTANCE.getDriverProfile(SynchronizationType.DEFAULT, (dkDriverProfileStatus, dkDriverProfile) -> {
    // Check status and use driverProfile
    return null;
});