Trip management

Configure the trip notification content

TripNotification is an object that contains the configuration of the foreground notification displayed during a trip recording.

To configure the trip notification in your app, call the following code:

DriveKitTripAnalysis

val notification = TripNotification(
    title = "Trip notification title",
    content = "Trip notification content",
    iconId = R.drawable.ic_notification
)
DriveKitTripAnalysis.tripNotification = notification

Attribute	Type	Description
title	String	Title of the notification
content	String	Content of the notification
iconId	Int	The icon Android resource identifier for notification
channelName	String	Name of the Android notification channel which is displayed in the app's notification settings. If not set, the channel name takes the value of title attribute
channelId	String	Identifier of the Android notification channel used. The default value is dq_sdk_channel
notificationId	Int?	The identifier of the foreground notification. If not set, the value is a strictly positive random integer and changes every time a trip recording is running.
contentIntent	PendingIntent?	The Intent which will be launched when the user taps on the notification. Default value is null.
enableCancel	Boolean	If true, a cancel button will be displayed in notification that cancels the trip when pressed. Default value is false.
cancel	String?	Text of the cancel button. Default value is null.
cancelIconId	Int?	Icon resource of the cancel button. Default value is null.

The cancelIconId and cancel parameters must be set if the enableCancel parameter is set to true.

Trip autostart

By default, the trip autostart feature is disabled.

To enable automatic trip detection, call the following method with parameter activate set to true.

DriveKitTripAnalysis

fun activateAutoStart(activate: Boolean)

If a trip is running when automatic trip detection is disabled, the trip will not be canceled. If you want to cancel the trip, you should also call cancelTrip method.

Manually start a trip

You can start a trip by calling the following method:

DriveKitTripAnalysis

fun startTrip()

If a trip is already started, calling this method will have no effect.

Stop a trip

You can stop a trip by calling the following method. The trip will be stopped instantly:

DriveKitTripAnalysis

fun stopTrip()

If a vehicle stops longer than the configured, the trip will be stopped automatically.

If no trip is running, calling this method will have no effect.

Cancel a trip

If you want to cancel a trip, you can call this method:

DriveKitTripAnalysis

fun cancelTrip()

Vehicle

To obtain a more precise analysis on driving behavior, it's recommended to configure the vehicle used by the driver. You can do this by calling the following method:

DriveKitTripAnalysis

fun setVehicle(vehicle: TripVehicle)

A detailed description of vehicle parameter is available here.

If no vehicle is configured a default vehicle will be configured with following parameters:

• carTypeIndex = 1

• carEngineIndex = 1

• carPower = 150

• carMass = 1400

• carGearboxIndex = 2

• carConsumption = 4.5

• engineDisplacement = 1200

• frontTireSize = "205/55/16"

• rearTireSize = "205/55/16"

• length = 4.5

• width = 1.8

• height = 1.45

• engineCylinderNb = 4

• driveWheels = 0

SDK recorder state

Two methods are available to determine SDK state.

DriveKitTripAnalysis

fun isTripRunning(): Boolean

This method returns false if the SDK is in INACTIVE state, and no trip is currently running.

If you want a more detailed state of the SDK, you can call the following method:

DriveKitTripAnalysis

fun getRecorderState(): State

This method returns the state of the SDK:

• INACTIVE: No trip is running.

• STARTING: The auto start mode detects a movement of the user and checks if it's a trip in vehicle.

• RUNNING: The trip has been confirmed by the speed of the movement.

• STOPPING: The SDK is in this state when a potential trip end is detected. If the trip continues, the SDK goes back in RUNNING state. The duration of the stopping state can be configured.

• SENDING: The trip is finished and is being sent to DriveQuant's server. When the SDK has the response from the server, the state becomes INACTIVE waiting for the next trip.

Get information about the current trip

When a trip recording is starting, you may need some information about it, like the StartMode which triggers the trip recording, a local unique identifier of the trip that has not yet been analyzed by the DriveQuant’s servers, etc.

• The local unique identifier generated by the SDK (localTripId) is different from the unique trip identifier generated after data analysis (itinId).

• A local trip identifier generated by the SDK (localTripId) is linked to a single unique trip identifier (itinId).

• If the trip is cancelled locally, there will be no trip analysis and therefore no unique trip identifier (itinId) linked to the unique local identifier (localTripId).

To retrieve information about the current trip, use the following method:

DriveKitTripAnalysis

fun getCurrentTripInfo(): DKTripInfo?

The method can return null if there is no trip currently recording.

DKTripInfo

Property	Type	Description
localTripId	String	Local and unique trip identifier generated by DriveKit SDK. ⚠️ It is different from the itinId property returned in the Trip object. itinId corresponds to the unique trip identifier generated after the data analysis.
date	Date	Start date of the trip recording. ⚠️ It is different from the startDate property returned in the Trip object.
startMode	StartMode	The StartMode which triggered the trip recording.

Manual trip repost

Trip Analysis SDK have a repost mechanism. In most cases, when a trip is finished, it is sent to DriveQuant's server for analysis. Once it's done, the result of the analysis is sent back to the SDK.

In some case, the trip can't be sent to DriveQuant's server (for example, when there is no network). In this case, the SDK will save the trip data locally to send it later.

An automatic retry will be attempted later when you are connected to network.

You can manually check whether trips are to be sent to the DriveQuant servers using the following method:

DriveKitTripAnalysis

fun checkTripToRepost()

If no trip is running or if the trip has been sent to the server and is currently being analyzed, calling this method will have no effect.

After a trip cancel, the automatic start function will not restart a new trip recording if the user has not walked. Without this mechanism, if the user cancels a trip recording because he is on public transport and not driving, the trip will restart immediately.

Custom stop timeout

A trip being analyzed is automatically terminated after a period of inactivity (which begins when the vehicle has stopped). The SDK allows to set the end-of-trip duration.

By default, the trip analysis is stopped after 240 seconds. This value can be tuned according to your need and you can choose any integer values between 120 and 480 seconds by calling the following method:

DriveKitTripAnalysis

fun setStopTimeOut(timeOut: Int)

If a value greater than 480 is set, the value will be forced to 480.

If a value lower than 120 is set, the value will be forced to 120.

Manage the location sharing while driving

Thanks to the driving location sharing feature, a user can generate a link that directs to a map displaying its location while driving. Location sharing provides peace of mind to family members during a trip. This section describes the methods to manage the location-sharing link.

Check if the feature is available

If the trip sharing feature is enabled for your company, your API key carries out the feature access and a trip sharing link can be generated.

To check if the trip sharing feature is available for your API key, you can call the following code:

Kotlin

DriveKitTripAnalysis.tripSharing.isAvailable()

Java

DriveKitTripAnalysis.getTripSharing().isAvailable()

Create a link

To generate a link to share trips, use the following code:

Kotlin

val oneHourInSeconds = 3600
DriveKitTripAnalysis.tripSharing.createLink(oneHourInSeconds) { status: CreateTripSharingLinkStatus, data: DKTripSharingLink? ->
    // Check the status and manage the data
}

Java

int oneHourInSeconds = 3600;
DriveKitTripAnalysis.getTripSharing().createLink(oneHourInSeconds, (CreateTripSharingLinkStatus status, DKTripSharingLink data) -> {
    // Check the status and manage the data
    return null;
});

The method takes a durationInSeconds parameter which indicates how long in seconds from now the sharing link will be valid.

CreateTripSharingLinkStatus

Value	Description
SUCCESS	The link has been successfully created. Information is returned in data.
ACTIVE_LINK_ALREADY_EXISTS	A link already exists for this user. Information returned in data is null. 💡 You have to call the method to retrieve an existing link in your workflow.
ERROR	An error occurred, for instance when the user has no network. Information returned in data is null.
USER_NOT_CONNECTED	The user is not yet connected to DriveKit. Information returned in data is null.
INVALID_DURATION	An error occurred when trying to create a link. The duration parameter must be strictly greater than 0. Information returned in data is null.
UNAUTHENTICATED	The user has been disconnected. Information returned in data is null.
FORBIDDEN	Your API key is not allowed to use the feature. Information returned in data is null.

DKTripSharingLink

Property	Type	Description
code	String	Unique trip sharing code.
url	String	URL of the map that will display the current trip of the user.
startDate	Date	Link validity start date
endDate	Date	Link expiration date.

Retrieve a valid sharing link

To retrieve a link to share trips, use the following code:

Kotlin

DriveKitTripAnalysis.tripSharing.getLink(SynchronizationType.DEFAULT) { status, data ->
    // Check the status and manage the data
}

Java

DriveKitTripAnalysis.getTripSharing().getLink(SynchronizationType.DEFAULT, (GetTripSharingLinkStatus status, DKTripSharingLink data) -> {
    // Check the status and manage the data
    return null;
});

The method takes a synchronizationType parameter. It will retrieve locally stored data if the value is CACHE, otherwise with the DEFAULT value it will call the DriveQuant’s servers.

GetTripSharingLinkStatus

Value	Description
SUCCESS	The link has been successfully retrieved. Information is returned in data.
FAILED_TO_GET_CACHE_ONLY	An error occurred when trying to retrieve a link. Locally trip sharing link, if exists, is returned in data.
NO_ACTIVE_LINK	There is no active link for the user. Information returned in data is null.
USER_NOT_CONNECTED	The user is not yet connected to DriveKit. Information returned in data is null.
UNAUTHENTICATED	The user has been disconnected. Information returned in data is null.
FORBIDDEN	Your API key is not allowed to use the feature. Information returned in data is null.

Revoke a trip sharing link

To revoke a trip sharing link, use the following code:

Kotlin

DriveKitTripAnalysis.tripSharing.revokeLink { status ->
    // Check the status and manage
}

Java

DriveKitTripAnalysis.getTripSharing().revokeLink((RevokeTripSharingLinkStatus status) -> {
    // Check the status
    return null;
});

RevokeTripSharingLinkStatus

Value	Description
SUCCESS	The link has been successfully revoked.
NO_ACTIVE_LINK	There is no active link for the user.
ERROR	An error occurred when trying to revoke the link.
USER_NOT_CONNECTED	The user is not yet connected to DriveKit.
UNAUTHENTICATED	The user has been disconnected.
FORBIDDEN	Your API key is not allowed to use the feature.

Sharing data during the trip

This feature allows you to share to the server the location of a driver during all his trips. It is different from the trip sharing with a link feature where the user chooses to share his trips for a certain duration, thanks to a link showing his current trip on a map.

The Trip Analysis component records the trip locally while it is in progress. The data are recorded with a period of one point per second. At the end of the trip, the SDK requests the driving analysis service and then retrieves the driving indicators.

In addition to this feature, the SDK is also able to share data with the server before the trip is completed. The data is transmitted at a lower frequency with a time interval of one point per minute.

The system for sharing information during the trip can be used in a vehicle fleet management system. This feature requires access to specific APIs. For more information, contact DriveQuant.

Sharing information with the server allows you to store the trip data even if it has been interrupted, and if the data post at the end of the trip could not be performed. This can happen in very rare cases such as the destruction of the mobile phone.

By default, this setting is disabled but you can enable it by calling the following method with parameter enable to true:

DriveKitTripAnalysis

fun enableSharePosition(enable: Boolean)

To disable this setting, call the same method with the parameter set to false

Here is the list of data shared every minute by the SDK:

• Date of trip start.

• Duration of the trip in seconds.

• Distance traveled in km.

• Longitude of the current location.

• Latitude of the current location.

• Smartphone battery level.

• StartMode of the trip recording: manual, GPS-based or beacon-based.

• Beacon parameters: uuid, major, minor.

If the crash detection is enabled and if a confirmed crash is detected by DriveKit, the data will be shared every 10 seconds instead of 1 minute until the trip finished.

Access the trip trigger events

Why use trip triggers?

DriveKit's automatic start mode detects a trip and launches its recording immediately. This operating mode may not be appropriate for all use cases.

Your application may require other information or business logic before enabling the trip recording. For example, it may be appropriate to check that:

• A connected device is near to the smartphone.

• The trip recording is acceptable in a given time slot.

In this case, you may want to subscribe to the events that are indicative of the trip start but not necessarily launch the GPS sensor and the trip analysis.

This is why DriveKit allows you to subscribe to trigger events that indicate that a trip has probably started.

How does it work?

By default, this feature is disabled.

To enable this feature, DriveKit Trip Analysis should not be configured in automatic mode but in manual mode.

If DriveKit Trip Analysis is set to automatic mode, the trip will be recorded.

If DriveKit Trip Analysis is set to manual mode and you follow the instructions below, you will be able to listen for trip start trigger events but the trip analysis will not be started automatically.

To listen to trigger events that indicate a start of trip, even if the autostart is disabled, you can check the following property:

DriveKitTripAnalysis

var monitorPotentialTripStart: Boolean

Once the feature is enabled, events will be available in the TripListener potentialTripStart() callback.

The potentialTripStart() method can return all StartMode values ; except MANUAL. Indeed, a trip manually started is considered as confirmed.

Get the arrival location of the last trip

This function returns the location of the end of the last trip recorded by the user.

The location is defined by GPS coordinates (latitude and longitude), along with the end date of the last trip and an accuracy indicator for the GPS reading.

You can use the end-of-trip coordinate for a variety of purposes, for example:

• help the user find his vehicle

• alert the customer that the user has reached a specific destination

• create a geofence to locate the vehicle

The last trip corresponds to the last trip recorded by the DriveKit SDK, regardless of the mode of transport used.

To retrieve the location at which the last recorded trip ended, use the following method:

DriveKitTripAnalysis

fun getLastTripLocation(): DKTripLocation?

The method can return null if the user:

• is not authenticated,

• or didn’t make a trip since the authentication,

• or hasn’t made any valid trips.

DKTripLocation

Property/Method	Type	Description
date	Date	Date of the end of trip.
latitude	Double	Latitude of the end of the trip.
longitude	Double	Longitude of the end of the trip.
accuracyMeter	Double	GPS data accuracy value in meters.
fun getAccuracyLevel()	DKCoordinateAccuracy	GPS data accuracy level. Possible values are described below.

DKCoordinateAccuracy

For ease of use, this function provides a position accuracy indicator with a 3-level scale.

Name	Description
GOOD	The GPS accuracy is strictly below 10 meters.
FAIR	The GPS accuracy is between 10 and 30 meters.
POOR	The GPS accuracy is strictly above 30 meters.

StartMode of the current trip

This method is now deprecated.

It is now possible to retrieve the start mode of the current trip using the getCurrentTripInfo() method.

Trip Analysis offers a method to retrieve the StartMode of the current trip. The method returns null if no trip is running.

DriveKitTripAnalysis

fun getCurrentStartMode(): StartMode?