Scoring

Handles ScoringAggregate and ScoringAverage related requests with IMS web services.
Scoring
You can get the average and maximum aggregate scores for previous trips taken by using the ScoringAggregateService. Functions have been added to query the scores over various different time periods. The time periods available are:
today
the last 7 days / last week
the last 30 days / last month
the last 90 days
the last 365 days
the last N days
custom date range
The definition of a day is based on the user's current timezone.
For the following, the example timezone should be considered to be UTC-0400 (i.e Toronto). If a request for today's data is made at on the 2nd day of the month, at 23:00 (11PM) UTC-0400, the result should be based on that specific day, even though the current date according to the UTC would be the 3rd day of the month. (11:00PM UTC-0400 corresponds to 03:00AM the next day on UTC-0000 time).
Some other examples: User's time: 2020-01-01 - 00:01AM UTC-0400 (04:01AM UTC-0000) Results: 2020-01-01
User's time: 2020-01-01 - 12:01PM UTC-0400 (04:01PM UTC-0000) Results: 2020-01-01
User's time: 2020-01-01 - 10:01PM UTC-0400 (2020-01-02 02:01AM UTC-0000) Results: 2020-01-01
Scoring Aggregate
An aggregate of scoring averages and sub scoring (braking, cornering, acceleration and speed).
Any valid user on the DriveSync system (identified via the Identity) should be able to know scoring aggregate.
Required information
*Identity: In order to fetch scoring data, the application must have a valid user (represented by the Identity). That user must be active.
Pre-made date ranges
There are some Pre-made requests for easy access to some commonly used date ranges, as they are commonly used for other scoring components. 
The current list includes:
Today
 Last 7 days
 Last 30 days
 Last 90 days
 Last 365 days
Today
Concrete example
To fetch the ScoringAggregate for the user for the today, one can use following snippet
Swift
Kotlin
let service = ScoringService(identity: identity)
service.today(then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})
val service = ScoringService(identity)
service.fetchTodaysDailyScores() { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})
Last 7 days
Concrete example
Fetch the ScoringAggregate for the user for the last 7 days, one can use following snippet
Swift
Kotlin
let service = ScoringService(identity: identity)
service.last7Days(then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})
val service = ScoringService(identity)
service.fetchLast7DaysDailyScores() { result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})
Other values
In order to get last 30, 90, and 365 days simply replace number "7" with the desired value respectively. 
Custom date range
Fetching data for the scoring aggregate requires a start and end date (range).
The date is assumed to be based on the user's current timezone. As an example, if the current user's timezone is set to UTC-5:00, the long 1603416046000 corresponds to 2020-10-22 (even though it corresponds to 2020-10-23 1:20AM UTC).
Concrete example
To fetch the ScoringAggregate for the user over a period of time with a start and end date(range), one can use following snippet
Swift
Kotlin
let service = ScoringService(identity: identity)
service.dateRange(from: Date(), to: Date(), then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})
val service = ScoringService(identity)
service.fetchDaily(from, to) { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})
Vehicle 
Fetching data for the scoring aggregate requires a start and end date (range).
Required information
*vehicle ID: In order to fetch scoring data for a vehicle, the application must have a valid vehicle associated with the identity.
Concrete example
To fetch the ScoringAggregate for a vehicle of the user over a period of time with a start and end date(range), one can use following snippet
Swift
Kotlin
service.fetchAggregateScoresByVehicle(vehicleId: vehicleId, from: Date(), to: Date(), then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})
val service = ScoringService(identity)
service.fetchAggregateScoresByVehicle(vehicleID, from, to) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})
To fetch the ScoringAggregate for a vehicle of the user for the past N days, the following can be used
Swift
Kotlin
service.fetchLastNDaysAggregateScoresByVehicle(vehicleId: vehicleId, days: days, then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})
val service = ScoringService(identity)
service.fetchLastNDaysAggregateScoresByVehicle(vehicleID, days) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})
Failures
ScoringService provides a [Throwable] in the results sent to the [ResultCallback].
The [Result] provided can be differentiated by checking the type of results, which is always [Result.Success] or [Result.Failure].
Alternatively, the [ResultCallback] can test for the presence of the throwable. 
scoringService.fetchTodaysScores(result -> {
   ScoringAggregate aggregate = result.getValue();
   if (aggregate != null) {
       setScoreTextValue("Daily: ", result.getValue());
   } else {
       NetworkException exception = (NetworkException) result.getThrowable();
       if (exception.getReason() == NetworkException.Reason.SERVER_NOT_FOUND) {
           showError("Server not found");
       }
   }
});
Scoring average
In all the above API's "Daily" can replaced by "Average" to get the corresponding response. 
Concrete example
For example to fetch the ScoringAverage for the user for the last 7 days, one can use following snippet
Swift
Kotlin
let service = ScoringService(identity: identity)
service.custom(from: fromDate, to: toDate, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}
val service = ScoringService(identity)
service.fetchLast7DaysAverageScores() { result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})
Note: In iOS (Swift) the method fetchLastNDaysAverageScores, has vehicle ID as optional. Please see vehicle​
Weekly average
To receive week by week score data, call fetchWeek api to recieve the desired data. The number passed as argument is a UInt representing the number of weeks you want the data. For example, to retreive current week you'll pass 0 and for last week you need to pass 1.
Concrete example
For example to fetch the ScoringAverage for the user for the desired week, one can use following snippet
Swift
Kotlin
let service = ScoringService(identity: identity)
service.fetchWeek(weekNumber: weekNumber, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}
val service = ScoringService(identity)
service.fetchWeek(weekNumber) { result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})
Vehicle
Fetching data for the scoring average requires a start and end date (range).
Required information
*vehicle ID: In order to fetch scoring data for a vehicle, the application must have a valid vehicle associated with the identity.
Concrete example
To fetch the ScoringAverage for a vehicle of the user over a period of time with a start and end date(range), one can use following snippet
Swift
Kotlin
let service = ScoringService(identity: identity)
service.fetchAverageScoresByVehicle(vehicleId: vehicleId, from: fromDate, to: toDate, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}
val service = ScoringService(identity)
service.fetchAverageScoresByVehicle(vehicleID, from, to) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})
To fetch the ScoringAverage for a vehicle of the user for the past N days, the following can be used.
Note: In iOS (Swift) the method fetchLastNDaysAverageScores, has vehicle ID as optional. If it is NOT passed, the api returns user's last N days average scores.  
Swift
Kotlin
let service = ScoringService(identity: identity)
service.fetchLastNDaysAverageScores(vehicleId: vehicleId, days: days, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}
val service = ScoringService(identity)
service.fetchLastNDaysAverageScoresByVehicle(vehicleID, days) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})
Discount
Vehicle
Last modified 8mo ago