Get Started

Before starting DriveKit Driver Achievement integration, make sure that you have initialized DriveKit, especially if you have disable the SDK auto-initialization.

If you use DriveKit Driver Achievement 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 the Driver Achievement module to your app, add the following line to your dependencies in your application build.gradle file:

dependencies {
    implementation 'com.drivequant.drivekit:drivekit-driver-achievement:$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 Achievement component. To initialize Driver Achievement component in your app, you must call the initialization method in onCreate method of your application class.

DriveKitDriverAchievement

fun initialize()

Get Streaks

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

DriveKitDriverAchievement

fun getStreaks(
        listener: StreaksQueryListener,
        synchronizationType: SynchronizationType = SynchronizationType.DEFAULT
)

SynchronizationType can have 2 values:

1. 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 callback.

2. CACHE: If this value is used, no synchronization will be performed and only trips previously synchronized will be returned via the callback.

StreakSyncStatus in the callback can have 3 values:

1. NO_ERROR: synchronization has been successfully performed.

2. CACHE_DATA_ONLY: synchronizationType has been set to cache.

3. FAILD_TO_SYNC_STREAKS_CACHE_ONLY: synchronization has failed, only streaks previously synchronized are returned.

Streak description

Attribute	Type	Description
theme	StreakTheme	Streak Theme identifier
current	StreakResult	Current streak result
best	StreakResult	Best streak result

Streak themes description

The themes and conditions to increment the sequences of the trip are the following:

• PHONE_DISTRACTION: the driver has not handled his phone.

• SAFETY: the safety score of the trip is higher or equal to 9.8.

• SPEEDING: the speeding score of the trip is higher or equal to 9.8.

• ACCELERATION: there wasn’t any harsh acceleration event during the trip.

• BRAKE: there wasn’t any hard braking event during the trip.

• ADHERENCE: there wasn’t any adherence thresold crossing during the trip.

• CALL: the driver has not made forbidden call during the trip.

Streak Result description

Attribute	Type	Description
distance	Double	Total distance travelled during streak
duration	Double	Total duration travelled during streak
tripNumber	Int	Number of trips performed within streak
startDate	Date	Date of the first trip of the streak
endDate	Date	Date of the last trip of the streak

Get Badges

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

DriveKitDriverAchievement

fun getBadges(
        listener: BadgesQueryListener,
        synchronizationType: SynchronizationType = SynchronizationType.DEFAULT
)

BadgeSyncStatus in the callback can have 3 values:

1. NO_ERROR : Synchronization has been successfully performed

2. CACHE_DATA_ONLY : SynchronizationType has been set to cache.

3. FAILED_TO_SYNC_BADGES_CACHE_ONLY : Synchronization has failed, only badges previously synchronized are returned.

If you want to notify users when they acquired a new set of badge you can get this value from the callback.

Get badge statistics

It can be practical to get some badge statistics, like how many badges have been won and how many remain to be acquired. To get these information, call the following method:

DriveKitDriverAchievement

fun getBadgeStatistics(): DKBadgeStatistics

DKBadgeStatistics

Field	Type	Description
acquired	Int	Total badge acquired by the user
remaining	Int	The number of badges not yet obtained
total	Int	Total badge count

Badge Description

Badge

Attribute	Type	Description
theme	String	Badge theme identifier
category	BadgeCategory	Badge category
BadgeCharacteristics	List<BadgeCharacteristics>	Badge properties

BadgeCharacteristics

Attribute	Type	Description
level	Level	Badge level
name	String	Badge name
icon	String	Badge icon name (for a won badge)
defaultIcon	String	Badge default icon name (for a pending badge)
descriptionValue	String	Clé localisable correspondant à la description pour l’affichage dans l'application.
progress	String	Badge progress message
progressValue	Double	Distance or number of trips performed
congrats	String	Badge congratulations message
threshold	Int	Distance or number of trips required to win the badge

Level

The Level enum values are:

• BRONZE

• SILVER

• GOLD

BadgeCategory

The BadgeCategory enum values are:

• GENERIC

• SAFETY

• ECO_DRIVING

• PHONE_DISTRACTION

Get ranking

To get driver’s ranking, you need to call the following method:

DriveKitDriverAchievement

fun getRanking(
        rankingType: RankingType,
        listener: RankingQueryListener,
        groupName: String? = null,
        rankingDepth: Int = 5,
        rankingPeriod: RankingPeriod = RankingPeriod.WEEKLY,
        synchronizationType: SynchronizationType = SynchronizationType.DEFAULT
)

Ranking parameters

Attribute	Type	Description
rankingPeriod	RankingPeriod	Period of the ranking
rankingDepth	int	Number of participants in the ranking higher and lower than the current user. It could be between 5 and 20.
rankingType	RankingType	Is the theme of the leaderboard.
synchronizationType	SynchronizationType	Whether data are fetch locally or from server.

RankingPeriod

The RankingPeriod enum values are:

• WEEKLY: is the period from the last Monday at midnight to the next Sunday at midnight.

• MONTHLY: is the period from the 1rst day of the month (at midnight) to the last (at midnight).

• ALL_TIME: is the period since the creation of the app.

RankingType

The RankingType enum values are:

• SAFETY,

• DISTRACTION,

• ECO-DRIVING,

• SPEEDING.

RankingSyncStatus

RankingSyncStatus 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_RANKINGS_CACHE_ONLY: Synchronization has failed, only rankings previously synchronized are returned.

• USER_NOT_RANKED: Driver not ranked.

Ranking Description

Attribute	Type	Description
rankingType	String	Theme of the ranking
rankingPeriod	String	Period of the ranking
groupName	String	Ranking group name
userPosition	Int	Position of the driver in the DriverRanked list
driverPreviousRank	Int	Previous driver’s rank
driversRanked	List<DriverRanked>	List of the rated drivers
nbDriverRanked	Int	Total number of rated drivers

DriverRanked Description

Attribute	Type	Description
userId	String	Unique identifier of the driver
nickname	String	Driver’s nickname
rank	Int	Driver’s rank in the leaderboard. This value is determined from the score rounded to 2 decimal places. If there is a tie, the one who has travelled the most distance is first.
score	Double	Driver’s score (according to the theme). This is the average of scores of the trips made in the period under consideration.
distance	Double	Covered distance by the driver in the specified period in km.

Ranking access conditions

To enter a ranking, a driver must fulfill the following requirements:

• Weekly ranking: 2 trips and 10 km since the first day of the week;

• Monthly ranking: 5 trips and 20 km since the first day of the month;

• Permanent ranking: 10 trips and 50 km since his first trip.

Data update

The scores, distances and ranks are updated every hour.