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
        }
    }
})

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:

Kotlin

DriveKitDriverData.updateDriverPassengerMode(
    itinId = "myItineraryId",
    mode = DriverPassengerMode.PASSENGER,
    comment = "I was the passenger"
) { status: UpdateDriverPassengerModeStatus ->
    when (status) {
        UpdateDriverPassengerModeStatus.SUCCESS -> {
            // Success, the data have been updated in the local database
        }
        UpdateDriverPassengerModeStatus.INVALID_ITINERARY_ID -> {
            // Error, the provided itinerary identifier does not exist or has not been made by the user
        }
        UpdateDriverPassengerModeStatus.INVALID_TRANSPORTATION_MODE -> {
            // Error, the trip was made with an alternative transport
        }
        UpdateDriverPassengerModeStatus.COMMENT_TOO_LONG -> {
            // Error, the comment is too long
        }
        UpdateDriverPassengerModeStatus.FAILED_TO_UPDATE_MODE -> {
            // An error occurred, for example when the user has no network.
        }
        UpdateDriverPassengerModeStatus.USER_NOT_CONNECTED -> {
            // An error occurred, the user is not yet connected.
        }
    }
}

Java

final String itinId = "myItineraryId";
final DriverPassengerMode mode = DriverPassengerMode.PASSENGER;
final String comment = "I was the passenger";
DriveKitDriverData.updateDriverPassengerMode(itinId, mode, comment, status -> {
    switch (status) {
        case SUCCESS -> {
            // Success, the data have been updated in the local database
        }
        case INVALID_ITINERARY_ID -> {
            // Error, the provided itinerary identifier does not exist or has not been made by the user
        }
        case INVALID_TRANSPORTATION_MODE -> {
            // Error, the trip was made with an alternative transport
        }
        case COMMENT_TOO_LONG -> {
            // Error, the comment is too long
        }
        case FAILED_TO_UPDATE_MODE -> {
            // An error occurred, for example when the user has no network.
        }
        case USER_NOT_CONNECTED -> {
            // An error occurred, the user is not yet connected.
        }
    }
    return null;
});

The method takes the following parameters:

Field	Type	Description
itinId	String	Unique trip identifier
mode	DriverPassengerMode	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.
USER_NOT_CONNECTED	The user is not yet connected to DriveKit.
INVALID_ITINERARY_ID	The itinerary identifier does not exist. Update is not taken into account and local trip data is not updated either.
INVALID_TRANSPORTATION_MODE	The trip was made with alternative transport. Update is not taken into account and local trip data is not updated either.
COMMENT_TOO_LONG	The comment exceeds 120 characters. Update is not taken into account and local trip data is not updated either.
FAILED_TO_UPDATE_MODE	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:

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;
});