# Get Started Before starting DriveKit Driver Achievement integration, make sure that you have [initialized DriveKit](https://docs.drivequant.com/get-started-drivekit/android), especially if you have [disable the SDK auto-initialization](https://docs.drivequant.com/get-started-drivekit/android/advanced-configurations#manually-initialize-the-sdk). {% hint style="danger" %} If you use DriveKit Driver Achievement 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 the Driver Achievement 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-achievement:$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 Achievement component. To initialize Driver Achievement component in your app, you must call the initialization method in `onCreate` method of your application class. {% tabs %} {% tab title="DriveKitDriverAchievement" %} ```kotlin fun initialize() ``` {% endtab %} {% endtabs %} ## **Get Streaks** To get Driver streaks, you have to call the following method: {% tabs %} {% tab title="DriveKitDriverAchievement" %} ```kotlin fun getStreaks( listener: StreaksQueryListener, synchronizationType: SynchronizationType = SynchronizationType.DEFAULT ) ``` {% endtab %} {% endtabs %} `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: {% tabs %} {% tab title="DriveKitDriverAchievement" %} ```kotlin fun getBadges( listener: BadgesQueryListener, synchronizationType: SynchronizationType = SynchronizationType.DEFAULT ) ``` {% endtab %} {% endtabs %} `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. {% hint style="info" %} If you want to notify users when they acquired a new set of badge you can get this value from the callback. {% endhint %} ### 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: {% tabs %} {% tab title="DriveKitDriverAchievement" %} ```kotlin fun getBadgeStatistics(): DKBadgeStatistics ``` {% endtab %} {% endtabs %} #### 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\ | 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: {% tabs %} {% tab title="DriveKitDriverAchievement" %} ```kotlin fun getRanking( rankingType: RankingType, listener: RankingQueryListener, groupName: String? = null, rankingDepth: Int = 5, rankingPeriod: RankingPeriod = RankingPeriod.WEEKLY, synchronizationType: SynchronizationType = SynchronizationType.DEFAULT ) ``` {% endtab %} {% endtabs %} ### **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\ | 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.