All pages
Powered by GitBook
1 of 3

Android

Get started

Prerequisite

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

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

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

fun initialize()

Synchronize list of challenges

To synchronize the list of challenges, call the following method:

fun getChallenges(
   listener: ChallengesQueryListener,
   synchronizationType: SynchronizationType = DEFAULT
)

ChallengesSyncStatus and Challenge models are described in the References part.

Take a look at the open-source code of our DriveKit Demo App to see how it is implemented.

Retrieve local challenge list

You can retrieve the list of challenges stored in the DriveKit local database by calling the previous method but with the SynchronizationType parameter to CACHE.

Synchronize challenge detail

You need to call the following method if you want to get more details and statistics about a defined challenge:

fun getChallengeDetail(
    	challengeId: String,
    	listener: ChallengeDetailQueryListener,
    	synchronizationType: SynchronizationType = DEFAULT
)

This method have the following parameters:

Field
Type
Description

challengeId

String

Unique identifier of the challenge

synchronizationType

SynchronizationType

Can be DEFAULT or CACHE.

- DEFAULT will synchronize the challenge detail by calling the DriveQuant servers

- CACHE will retrieve the challenge detail already synchronized in the local database.

ChallengeDetailSyncStatus and ChallengeDetail models are described in the References part.

Take a look at the open-source code of our DriveKit Demo App to see how it is implemented.

Retrieve local challenge detail data

You can retrieve the details of a given challenge stored in the DriveKit local database by calling the previous method but with the SynchronizationType parameter to CACHE.

Join a challenge

To be able to join a given challenge, you can call the following method:

fun joinChallenge(
    	challengeId: String,
    	listener: JoinChallengeQueryListener
)

This method have the following parameter:

Field
Type
Description

challengeId

String

Unique identifier of the challenge

JoinChallengeSyncStatus enum values are described in the References part.

Take a look at the open-source code of our DriveKit Demo App to see how it is implemented.

References (Android)

ChallengesSyncStatus

Value
Description

SUCCESS

Synchronization has been successfully performed.

CACHE_DATA_ONLY

SynchronizationType has been set to CACHE.

FAILED_TO_SYNC_CHALLENGES_CACHE_ONLY

Synchronization has failed, only challenges previously synchronized are returned

SYNC_ALREADY_IN_PROGRESS

Another challenge list synchronization is already in progress

Challenge

Field
Type
Description

challengeId

String

Unique identifier of the challenge

challengeType

ChallengeType

Type of the challenge

title

String

Title of the challenge

description

String

Description of the challenge

conditionsDescription

String?

Description of the challenge’s conditions to be filled.

startDate

Date

Challenge’s start date

endDate

Date

Challenge’s end date

conditions

Map<String, String>

Required conditions to participate.

Possible keys of the map are: km and nbTrip.

Remark: All conditions must be met in order to participate.

rankKey

String?

Deprecated.

themeCode

Int

Deprecated

type

Int

Deprecated.

isRegistered

Boolean

Equals true if the user participates in the challenge.

conditionsFilled

Boolean

Equals true if the conditions are filled by the user to access the challenge.

driverConditions

Map<String, String>

Current driver values for conditions to participate in the challenge.

Possible keys of the map are: km and nbTrip

groups

List<ChallengeGroup>

Groups that can view and participate to the challenge

rules

String?

Rules of the current challenge

optinText

String?

Opt-in text of the current challenge

status

ChallengeStatus

Current status of the challenge

nbDriverRegistered

Int

Number of drivers registered for this challenge

nbDriverRanked

Int

Number of drivers ranked for this challenge

rank

Int

Current rank of the driver. Equals 0 if the driver is not registered or not ranked for this challenge.

ChallengeType

Value
Description

SAFETY

The challenge is based on the safety score

ECODRIVING

The challenge is based on the ecodriving score

DISTRACTION

The challenge is based on the distraction score

SPEEDING

The challenge is based on the speeding score

HARD_BRAKING

The challenge is based on the number of hard braking

HARD_ACCELERATION

The challenge is based on the number of hard acceleration

DEPRECATED

The challenge type is deprecated. You should ignore it in your graphical interface.

UNKNOWN

The challenge type is unknown. You have to ignore it in your graphical interface.

Value
Description

101

Challenge based on eco driving score

201

Challenge based on safety score

205

Challenge based on the number of hard brakings

209

Challenge based on the number of hard acceleration

221

Challenge based on distraction score

401

Challenge based on speeding score

ChallengeGroup

Field
Type
Description

id

String

Group identifier

label

String

Label of the group

ChallengeStatus

Value
Description

FINISHED

The challenge is finished.

SCHEDULED

The challenge has not started yet.

PENDING

The challenge is in progress.

ARCHIVED

The challenge is finished and is archived. It should not appear in the list

ChallengeDetailSyncStatus

Value
Description

SUCCESS

Synchronisation has been successfully performed.

CHALLENGE_NOT_FOUND

There is no existing challenge with this challengeId.

CACHE_DATA_ONLY

synchronizationType has been set to CACHE.

FAILED_TO_SYNC_CHALLENGE_DETAIL_CACHE_ONLY

Synchronisation has failed, only challenge detail previously synchronized is returned.

SYNC_ALREADY_IN_PROGRESS

Another challenge detail retrieval for this identifier is already in progress

ChallengeDetail

Field
Type
Description

challengeId

String

Identifier of the challenge

driverStats

ChallengeDriverStats

Driver’s statistics of the challenge

challengeStats

ChallengeStats

Global statistics of the challenge

driversRanked

List<ChallengeDriverRanked>?

Ranked drivers list.

userIndex

Int

Position of the user in the driversRanked list

nbDriverRegistered

Int

Number of drivers registered for this challenge

nbDriverRanked

Int

Number of drivers ranked for this challenge

isRegistered

Boolean

Equals true if the user is registered to the challenge

conditionsFilled

Boolean

Equals true if the user has filled the condition to be ranked.

itinIds

List<String>

List of itinerary IDs made by the user during the challenge.

ChallengeDriverStats

Field
Type
Description

rank

Int

Driver’s rank for this challenge

numberTrip

Int

Number of trips made during the challenge

distance

Double

Total distance (in km) made during the challenge

duration

Double

Total duration (in hours) of the trips made during the challenge

score

Double

Score for the challenge

ChallengeStats

Field
Type
Description

numberDriver

Int

Total number of drivers participating in the challenge

numberTrip

Int

Total number of trips done for this challenge

distance

Double

Total distance (in km) travelled for this challenge

duration

Double

Total trips duration (in hours) of the challenge

score

Double

Average challenge score

minScore

Double

Lowest score for this challenge

maxScore

Double

Best score for this challenge

ChallengeDriverRanked

Field
Type
Description

pseudo

String

Pseudo of the driver

rank

Int

Driver’s rank

score

Double

Driver’s score on ten

previousRank

Int

Driver’s previous rank

distance

Double

Distance travelled by the driver (in km)

JoinChallengeSyncStatus

Value
Description

JOIN_SUCCESS

The challenge is joined successfully

ALREADY_JOINED

The user has already joined the given challenge

CHALLENGE_NOT_FOUND

There is no existing challenge with this challengeId

FAILED_TO_JOIN

Couldn’t join the challenge. Can occur for example if the user has no network