Skip to content

Migration Guide 3.7

Migration SDK from Old Versions

This section provides a detailed description of API changes introduced or removed in recent SDK upgrades.
We strongly recommend reading this documentation when upgrading the SDK version to understand the differences and update your API calls accordingly.

Migration to Version 3.7.0

New Contextual Coaching APIs

Version 3.7.0 introduces new contextual coaching APIs with an asynchronous processing pattern. The old getContextualCoachingStatisticsRequest is now deprecated in favor of a two-step process: Post Contextual Coaching Request and Get Contextual Coaching Request.

Old API (Deprecated):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// Deprecated - use new two-step process
val request = driveMotionAnalyticsClient
    .getContextualCoachingStatisticsRequest()
    .withCurrentPeriod(startDate, endDate)
    .withPreviousPeriod(previousStartDate, previousEndDate)
    .withAsset(assetId, assetContext)
    .withTimezone(timezone)
    .withScoreVersion(scoreVersion)
    .groupBy(groupFactors)
    .rankBy(rankMetrics)
    .build()

New API (Recommended):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// Step 1: Post contextual coaching request
val postRequest = driveMotionAnalyticsClient
    .postContextualCoachingRequest(startTime, endTime, timeZoneId)
    .withAsset(assetId, assetContext)
    .withScoreVersion(scoreVersion)
    .groupBy(groupFactors)
    .rankBy(rankMetrics)
    .build()

postRequest.execute { postResponse ->
    if (postResponse.status == ResponseStatus.SUCCESS) {
        postResponse.result?.coachingId?.let { 
            getContextualCoachingResult(it) 
        }
    }
}

// Step 2: Get contextual coaching result
fun getContextualCoachingResult(coachingId: String) {
    driveMotionAnalyticsClient
        .getContextualCoachingRequest(coachingId)
        .build()
        .execute { getResponse ->
            when (getResponse.result?.coachingStatus) {
                ProcessStatus.COMPLETED -> {
                    if (getResponse.result?.statusReason == null) {
                        // Process statistics
                    }
                }
                ProcessStatus.PENDING, ProcessStatus.PROCESSING -> {
                    // Retry after delay
                }
                ProcessStatus.FAILED -> {
                    // Handle error
                }
            }
        }
}

Key Changes: - Replaced synchronous API with async two-step process (Post + Get) - Single time range instead of currentPeriod and previousPeriod - Status checking required: COMPLETED, PENDING, PROCESSING, FAILED

Get Trips by IDs API

New API to retrieve specific trips using their unique identifiers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
val request = driveMotionAnalyticsClient
    .getTripsByIdsRequest(tripIds)
    .withAsset(assetId, assetContext)
    .withExcludeTripEvents(false)
    .withExcludeTripRoute(false)
    .build()

request.execute { response ->
    response.trips?.forEach { trip ->
        // Process trip
    }
}

Notes: - Maximum 50 trips per request in cloud mode - Vehicle-based only (requires withAsset()) - Use withExcludeTripEvents() and withExcludeTripRoute() to optimize response size

Safety Score Version Support Improvements

Enhanced support for different safety score versions across multiple APIs: - AggregatedSafetyScoreRequest - GetContextualCoachingRequest (new) - PostContextualCoachingRequest (new) - GetEventPercentileTableRequest

1
2
3
4
5
6
7
val request = driveMotionAnalyticsClient
    .aggregatedSafetyScoreRequest()
    .withStartDate(startDate)
    .withEndDate(endDate)
    .withScoreVersion("V1.0.5")
    .withAsset(assetId, assetContext)
    .build()

Backward Compatibility

The old getContextualCoachingStatisticsRequest API will continue to work but is deprecated and will be removed in a future release. We recommend migrating to the new APIs.