Get started

Prerequisite
Before starting DriveKit Driver Achievement integration, make sure that you have initialized DriveKit.
Integration
Get framework
DriveKit Driver Achievement SDK is available on CocoaPods master repo.
To access the framework in the repository, add the following lines to your Podfile:
Podfile
1
target 'my-target' do
2
  pod 'DriveKitDriverAchievement'
3
end
Copied!
Then, run pod install.
Get Streaks
To get Driver streaks, you have to call the following method:
1
public func getStreaks(type: SynchronizationType = .defaultSync, completionHandler : @escaping (StreakSyncStatus, [Streak]) -> ())
Copied!
SynchronizationType can have 2 values:
1.
defaultSync: if this value is used, the SDK will try to synchronize local trips with DriveQuant backend to get new streaks or modified streaks, and then return the streak list via the completionHandler.
2.
cache: if this value is used, no synchronization will be performed and only streaks previously synchronized will be returned via the completionHandler.
StreakSyncStatus in the completionHandler can have 4 values:
1.
noError: synchronization has been successfully performed.
2.
cacheDataOnly: synchronizationType has been set to cache.
3.
failedToSyncStreakCacheOnly: synchronization has failed, only streaks previously synchronized are returned.
4.
syncAlreadyInProgress: a synchronization is in progress, only streaks previously synchronized are returned until the synchronization is finished.
Streak description
Attribute
Type
Description
theme
DKStreakTheme
Streak Theme identifier
current
DKStreakResult
Current streak result
best
DKStreakResult
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 threshold crossing during the trip.
Streak Result description
Attribute
Type
Description
distance
Double
Total distance travelled during streak (in meters)
duration
Double
Total duration travelled during streak (in seconds)
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, your have to call the following method:
1
public func getBadges(type: SynchronizationType = .defaultSync, completionHandler : @escaping (BadgeSyncStatus, [DKBadge], Int) -> ())
Copied!
SynchronizationType can have 2 values:
1.
defaultSync: if this value is used, the SDK will try to synchronize local trips with DriveQuant backend to get new or updated badges, and then return the badge list via the completionHandler.
2.
cache: If this value is used, no synchronization will be performed and only badges previously synchronized will be returned via the completionHandler.
BadgeSyncStatus in the completionHandler can have 4 values:
1.
noError: Synchronization has been successfully performed.
2.
cacheDataOnly: SynchronizationType has been set to cache.
3.
failedToSyncStreakCacheOnly: Synchronization has failed, only badges previously synchronized are returned.
4.
syncAlreadyInProgress: A synchronization is in progress, only badges previously synchronized are returned until the synchronization is finished.
Badge description
DKBadge
Attribute
Type
Description
theme
String
Badge theme identifier
category
DKBadgeCategory
Badge category
badgeCharacteristics
[DKBadgeCharacteristics]
Badge properties
DKBadgeCharacteristics
Attribute
Type
Description
level
DKLevel
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
Badge goal description
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
DKLevel
.bronze
.silver
.gold
DKBadgeCategory
.generic
.ecodriving
.safety
.phoneDistraction
Get ranking
To get driver’s Ranking, you need to call the following method of DriveKitDriverAchievement class:
1
func getRanking(rankingType: DKRankingType,
2
                rankingPeriod: DKRankingPeriod = .weekly,
3
                rankingDepth: Int = 5,
4
                groupName: String = "All",
5
                type: SynchronizationType = .defaultSync,
6
                completionHandler : @escaping (RankingSyncStatus, DKRanking?) -> ())
Copied!
Ranking parameters
Attribute
Type
Description
rankingType
DKRankingType
Theme of the ranking. 
rankingPeriod
DKRankingPeriod
Period of the ranking.
rankingDepth
Int
This integer value must be between 5 and 20.
If you set this value to 5, the leaderboard will display: 
the top 5 users in the ranking
the position of the connected user
the positions of the 5 best neighbors of the connected user
the positions of the 5 worst neighbors of the connected user
type
SynchronizationType
Whether data are fetch locally or from server.
DKRankingType
The DKRankingType enum values are:
safety, 
ecoDriving, 
distraction,
speeding.
DKRankingPeriod
The DKRankingPeriod enum values are:
weekly: In the case of a weekly classification, the trips considered for the calculation of the user's position are those made between Monday midnight and Sunday midnight. If the user has not driven during the week, he is not ranked.
monthly: In the case of a monthly ranking, the trips considered for the calculation of the user's position are those made between the first and last day of the month.. If the user has not driven during this period, he is not ranked.
allTime: This ranking takes into account all of the driver's trips.
RankingSyncStatus
RankingSyncStatus in the callback can have 5 values:
Synchronization status:
1.
noError: Synchronization has been successfully performed.
2.
cacheDataOnly: SynchronizationType has been set to cache.
3.
failedToSyncRanking: Synchronization has failed, only rankings previously synchronized are returned.
4.
syncAlreadyInProgress: A synchronization is in progress, only rankings previously synchronized are returned until the synchronization is finished.
5.
userNotRanked: The user is not ranked.
DKRanking Description
Attribute
Type
Description
rankingType
DKRankingType
Theme of the ranking
rankingPeriod
DKRankingPeriod
Period of the ranking
userPosition
Int
Position of the driver in the driversRanked list
userPreviousPosition
Int?
Previous position of the driver in the ranking
driversRanked
[DKDriverRanked]
List of the rated drivers
nbDriverRanked
Int
Total number of rated drivers
DKDriverRanked Description
Attribute
Type
Description
userId
String?
Unique identifier of the driver
nickname
String?
Driver’s nickname
rank
Int
Driver’s rank in the ranking.
This value is determined from the rounded score (to 2 decimal places). If two drivers have the same score, the one with the highest distance is considered as the first one.
score
Double
Driver’s score (according to the theme). 
It corresponds to the average of all trip scores made during the specified period.
distance
Double
Covered distance by the driver in the specified period
Ranking access conditions
To enter a ranking, a driver must have at least one scored trip during the ranking period.
Data update
The scores, distances and ranks are updated every hour.
Reset
If you need to reset Driver Achievement configuration (user logout for example), you can call the following method:
1
DriveKitDriverAchievement.shared.reset()
Copied!
All data saved locally by the Driver Achievement SDK will be erased and default configuration will be restored.
​