# Get started

## Prerequisite

Before starting DriveKit Driver Data integration, make sure that you have [initialized DriveKit](https://docs.drivequant.com/get-started-drivekit/android).

{% hint style="danger" %}
If you use DriveKit Driver Data without having initialized DriveKit, an exception will be generated and the SDK will not work in your application.
{% endhint %}

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

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

{% hint style="info" %}
Replace `$drivekit_version` with the DriveKit version you are using in your app
{% endhint %}

## Initialization

If you have [disabled the SDK auto-initialization](https://docs.drivequant.com/get-started-drivekit/android/advanced-configurations#manually-initialize-the-sdk), 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.

{% tabs %}
{% tab title="DriveKitDriverData" %}

```kotlin
fun initialize()
```

{% endtab %}
{% endtabs %}

## Get driver trips

To get [Driver trips](https://docs.drivequant.com/trip-analysis/android/references#trip), you have to call the following method:

{% tabs %}
{% tab title="DriveKitDriverData" %}

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

{% endtab %}
{% endtabs %}

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

```kotlin
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](https://docs.drivequant.com/trip-analysis/android/references#trip) objects.

{% hint style="info" %}
Trips are returned and sorted by end date in descending order.
{% endhint %}

Example:

```kotlin
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](https://docs.drivequant.com/trip-analysis/android/references#trip), you have to call the following method:

{% tabs %}
{% tab title="DriveKitDriverData" %}

```kotlin
fun getTrip(itinId: String, listener: TripQueryListener)
```

{% endtab %}
{% endtabs %}

The `itinId` parameter is the unique identifier for a trip.

An implementation of `TripQueryListener` must be provided in order to retrieve the trip.&#x20;

```kotlin
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](https://docs.drivequant.com/ios/get-started#get-driver-trips) 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](https://docs.drivequant.com/trip-analysis/android/references#trip) object, if exists.

Example:

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

{% tabs %}
{% tab title="DriveKitDriverData" %}

```kotlin
fun getRoute(itinId: String, listener: RouteQueryListener)
```

{% endtab %}
{% endtabs %}

An implementation of `RouteQueryListener` must be provided in order to retrieve the trip.&#x20;

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

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

{% tabs %}
{% tab title="DriveKitDriverData" %}

```kotlin
fun deleteTrip(itinId: String, listener: TripDeleteQueryListener)
```

{% endtab %}
{% endtabs %}

The `itinId` parameter is the unique identifier for a trip.

Example:

```kotlin
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.

{% hint style="warning" %}
When a user declares that a trip was made as a passenger, it will **not** modify any scores related to the trip.
{% endhint %}

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

{% tabs %}
{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="Java" %}

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

{% endtab %}
{% endtabs %}

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:

<table><thead><tr><th width="316">Value</th><th>Description</th></tr></thead><tbody><tr><td>SUCCESS</td><td>The passenger status has been successfully updated and local trip data is also updated.</td></tr><tr><td>USER_NOT_CONNECTED</td><td>The user is not yet connected to DriveKit.</td></tr><tr><td>INVALID_ITINERARY_ID</td><td>The itinerary identifier does not exist.<br>Update is not taken into account and local trip data is not updated either.</td></tr><tr><td>INVALID_TRANSPORTATION_MODE</td><td>The trip was made with alternative transport.<br>Update is not taken into account and local trip data is not updated either.</td></tr><tr><td>COMMENT_TOO_LONG</td><td>The comment exceeds 120 characters.<br>Update is not taken into account and local trip data is not updated either.</td></tr><tr><td>FAILED_TO_UPDATE_MODE</td><td>An error has occurred, for example if the user has no network.<br>Update is not taken into account and local trip data is not updated either.</td></tr></tbody></table>

## **Get driver synthesis**

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

{% tabs %}
{% tab title="DriveKitDriverData" %}

```kotlin
fun getSynthesis(
   listener: SynthesisQueryListener,
   synchronizationType: SynchronizationType)
```

{% endtab %}
{% endtabs %}

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

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

{% tabs %}
{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="Java" %}

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

{% endtab %}
{% endtabs %}

## Get **driver timelines**

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

{% tabs %}
{% tab title="DriveKitDriverData" %}

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

{% endtab %}
{% endtabs %}

| Parameter name               | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| periods                      | `DKTimelinePeriod`  | <p>Get timeline data in a specific period of time.<br>Possible values are : <code>WEEK</code>, <code>MONTH</code>, <code>YEAR.</code></p>                                                                                                                                                                                                                                                               |
| synchronizationType          | SynchronizationType | <p>Define the source of the timelines data you want to retrieve.<br><br>Possible values are:<br><br><code>CACHE</code>: No sync will be performed and the data retrieved during the last sync will be returned via the <code>callback</code>.</p><p><br><code>DEFAULT</code>: the SDK will try to synchronize timelines with DriveQuant backend and then return them via the <code>callback</code>.</p> |
| ignoreItemsWithoutTripScored | Boolean             | If set to `true`, the returned timeline data will not contain items ([DKAllContextItem](https://docs.drivequant.com/driver-data/references#dkallcontextitem) and [DKRoadContextItem](https://docs.drivequant.com/driver-data/references#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](https://docs.drivequant.com/driver-data/android/references#dkdrivertimeline) object, one per requested period.

## Get driver profile

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

{% tabs %}
{% tab title="DriveKitDriverData" %}

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

{% endtab %}
{% endtabs %}

`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`](https://docs.drivequant.com/driver-data/references#dkdriverprofile) object requested.

Example:

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
import com.drivequant.drivekit.driverdata.DriveKitDriverData

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

{% endtab %}

{% tab title="Java" %}

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

{% endtab %}
{% endtabs %}