LogoLogo
ProductsUse casesDocsSupport
  • Introducing DriveKit
  • DriveKit Guides
  • Get started with drivekit
    • Trip recording lifecycle
    • iOS
      • 🚀Quick start
      • Advanced configurations
      • References
      • iOS DriveKit Demo App
    • Android
      • 🚀Quick start
      • Advanced configurations
      • References
      • Android DriveKit Demo App
      • Android 15 Migration guide
      • Android 14 Migration guide
      • Troubleshooting
  • Trip analysis
    • Introduction
    • iOS
      • Permissions
      • Trip management
      • TripListener
      • Crash Detection
      • Beacon usage
      • Bluetooth usage
      • Custom metadata
      • References (iOS)
    • Android
      • Runtime permissions
      • Trip management
      • TripListener
      • Crash Detection
      • Beacon usage
      • Bluetooth usage
      • Custom metadata
      • References (Android)
    • User interface
      • iOS
        • Get started
        • Working hours
        • Driver alert in case of crash
        • Trip recording widget
        • Location sharing
      • Android
        • Get started
        • Working hours
        • Driver alert in case of crash
        • Trip recording widget
        • Location sharing
    • REST services
      • Trip
      • References
    • Trip Simulator
      • iOS
      • Android
  • PERMISSIONS UTILS
    • Introduction
    • User interface
      • iOS
        • Get started
        • Main configurations
      • Android
        • Get started
        • Main configurations
  • COMMON UI
    • Introduction
    • iOS
      • Get started
    • Android
      • Get started
    • References
  • DRIVER DATA
    • Introduction
    • iOS
      • Get started
      • References (iOS)
    • Android
      • Get started
      • References (Android)
    • User interface
      • iOS
        • Get started
        • Advanced configurations
        • Trips widgets
        • My Synthesis
        • My Driver Profile
      • Android
        • Get Started
        • Advanced configurations
        • Trips widgets
        • My Synthesis
        • My Driver Profile
  • Driver Data Timeline UI
    • Introduction
    • iOS
      • Get started
    • Android
      • Get started
  • Vehicle
    • Introduction
    • iOS
      • Get started
      • Vehicle management
      • Beacon management
      • Bluetooth device management
      • Odometer
      • References (iOS)
    • Android
      • Get started
      • Vehicle management
      • Beacon management
      • Bluetooth device management
      • Odometer
      • References (Android)
    • User interface
      • iOS
        • Get started
        • Main configurations
        • Advanced configurations
      • Android
        • Get started
        • Main configurations
        • Advanced configurations
  • DRIVER ACHIEVEMENT
    • Introduction
    • iOS
      • Get started
    • Android
      • Get Started
    • User interface
      • iOS
      • Android
  • CHALLENGE
    • Introduction
    • Important challenge rules
    • iOS
      • Get started
      • References (iOS)
    • Android
      • Get started
      • References (Android)
    • User interface
      • iOS
        • Get started
      • Android
        • Get started
  • GROUP
    • Introduction
    • iOS
      • Get started
    • Android
      • Get started
  • React Native
    • Get started
    • Integration
  • Flutter
    • Get started
    • Integration
  • Push services
    • Introduction
    • Push Trip Data
    • Push Deleted trip
    • Push Crash Data
    • Push Diagnosis Data
  • ADMIN SERVICES
    • Beacon
      • Add
      • Replace
      • Delete
      • Configuration
    • Challenges
      • List of challenges
      • Challenge details
      • Registered users
      • Challenge ranking
      • Users' progress
      • Definitions
    • Customer
      • Activity timeline
    • Driver
      • Timeline
      • Synthesis
      • Identity
      • Status
      • Add or update a metadata
      • Vehicles
      • Profile
      • Application diagnoses
    • Drivers
      • Account
      • Statistics
      • Ranking
      • Expired accounts
    • Group
      • Timeline
      • Synthesis
    • Trips
      • Add or update a metadata
      • Delete a metadata
    • Vehicle
      • Create
      • Characteristics
      • Configuration
      • Statistics
      • Update mileage
      • Tire and brake wear update
      • References
  • Crashes
    • Annotate a crash
    • Revoke crash location URL
  • ENTERPRISE SERVICES
    • Introduction
    • Teams
      • Create a team
      • List of teams
      • Enable or disable a team
    • Hyper-admins
      • Create a hyper-admin
      • List of hyper-admins
      • Delete a hyper-admin
    • Monitoring
      • Get a push trip data report
      • Get a push crash data report
      • Request to retry failed trips
      • Request to retry failed crashes
      • Get the status of a task
  • Release notes
    • Changelog
      • iOS
      • Android
      • UI iOS
      • UI Android
Powered by GitBook
On this page
  • Prerequisite
  • Integration
  • Get module from repository
  • Initialization
  • Get driver trips
  • Get specific trip
  • Get trip road data
  • Delete a trip
  • Declare a trip made as passenger
  • Get driver synthesis
  • Get driver timelines
  • Get driver profile

Was this helpful?

Export as PDF
  1. DRIVER DATA
  2. Android

Get started

PreviousAndroidNextReferences (Android)

Last updated 2 days ago

Was this helpful?

Prerequisite

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

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 , 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.

fun initialize()

Get driver trips

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

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

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.

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:

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:

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:

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

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:

DriveKitDriverData.getSynthesis(object : SynthesisQueryListener {
    override fun onResponse(
        synthesisStatus: SynthesisStatus,
        synthesis: Synthesis?
    ) {
        // Check synthesisStatus and use synthesis data
    }
})
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:

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

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.

Get driver profile

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

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.

Example:

import com.drivequant.drivekit.driverdata.DriveKitDriverData

DriveKitDriverData.getDriverProfile(type: DKDriverProfileStatus.DEFAULT) { status, driverProfile ->
    // Check status and use driverProfile
}
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;
});

To get , you have to call the following method:

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

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

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

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

If set to true, the returned timeline data will not contain items ( and ) where there are only unscored trips.

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

The second argument in the callback is the object requested.

DKDriverTimeline
initialized DriveKit
above
disabled the SDK auto-initialization
Driver trips
Trip
trip
Trip
DKDriverProfile
DKAllContextItem
DKRoadContextItem