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
12
13
// Deprecated - use new two-step process
let builder = driveMotionAnalyticsClient.getContextualCoachingStatisticsRequest()
let currentPeriod = DateRange(start: startDate, end: endDate)

let request = try builder
    .currentPeriod(currentPeriod)
    .previousPeriod(previousPeriod)
    .asset(assetId: assetId, assetContext: assetContext)
    .timezone(timezone)
    .scoreVersion(scoreVersion)
    .groupBy(groupFactors)
    .rankBy(rankMetrics)
    .build()

1
2
3
4
5
6
7
// Deprecated
TNGetContextualCoachingStatisticsRequestBuilder *builder = [client getContextualCoachingStatisticsRequest];
DateRange *currentPeriod = [[DateRange alloc] initWithStart:startDate end:endDate];
[builder currentPeriod:currentPeriod];
[builder previousPeriod:previousPeriod];
[builder assetWithAssetId:assetId assetContext:assetContext];
TNGetContextualCoachingStatisticsRequest *request = [builder buildAndReturnError:&error];

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
39
40
41
// Step 1: Post contextual coaching request
let builder = driveMotionAnalyticsClient.postContextualCoachingRequest(
    startTime: startTime,
    endTime: endTime,
    timeZoneId: timeZoneId
)
let request = try builder
    .asset(assetId: assetId, assetContext: assetContext)
    .scoreVersion(scoreVersion)
    .groupBy(groupFactors)
    .rankBy(rankMetrics)
    .build()

let call = TNPostContextualCoachingCall()
call.execute(request: request) { (response, error) in
    if let coachingId = response?.result?.coachingId {
        getContextualCoachingResult(coachingId: coachingId)
    }
}

// Step 2: Get contextual coaching result
func getContextualCoachingResult(coachingId: String) {
    let builder = driveMotionAnalyticsClient.getContextualCoachingRequest(coachingId: coachingId)
    let request = try builder.build()

    let call = TNGetContextualCoachingCall()
    call.execute(request: request) { (response, error) in
        switch response?.result?.coachingStatus {
        case .completed:
            if response?.result?.statusReason == nil {
                // Process statistics
            }
        case .pending, .processing:
            // Retry after delay
        case .failed:
            // Handle error
        default:
            break
        }
    }
}

 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
// Step 1: Post contextual coaching request
TNPostContextualCoachingRequestBuilder *builder = [client postContextualCoachingRequestWithStartTime:startTime endTime:endTime timeZoneId:timeZoneId];
[builder assetWithAssetId:assetId assetContext:assetContext];
TNPostContextualCoachingRequest *request = [builder buildAndReturnError:&error];

TNPostContextualCoachingCall *call = [[TNPostContextualCoachingCall alloc] init];
[call executeWithRequest:request callback:^(TNPostContextualCoachingResponse *response, TNDriveMotionException *error) {
    if (response.result.coachingId) {
        [self getContextualCoachingResultWithCoachingId:response.result.coachingId];
    }
}];

// Step 2: Get contextual coaching result
- (void)getContextualCoachingResultWithCoachingId:(NSString *)coachingId {
    TNGetContextualCoachingRequestBuilder *builder = [client getContextualCoachingRequestWithCoachingId:coachingId];
    TNGetContextualCoachingRequest *request = [builder buildAndReturnError:&error];

    TNGetContextualCoachingCall *call = [[TNGetContextualCoachingCall alloc] init];
    [call executeWithRequest:request callback:^(TNGetContextualCoachingResponse *response, TNDriveMotionException *error) {
        switch (response.result.coachingStatus) {
            case TNProcessStatusCompleted:
                if (response.result.statusReason == nil) {
                    // Process statistics
                }
                break;
            case TNProcessStatusPending:
            case TNProcessStatusProcessing:
                // Retry after delay
                break;
            case TNProcessStatusFailed:
                // Handle error
                break;
            default:
                break;
        }
    }];
}

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
13
let request = try driveMotionAnalyticsClient
    .getTripsByIdsRequest(tripIds: tripIds)
    .asset(assetId: assetId, assetContext: assetContext)
    .excludeTripEvents(false)
    .excludeTripRoute(false)
    .build()

let call = TNGetTripsByIdsCall()
call.execute(request: request) { (response, error) in
    response?.trips?.forEach { trip in
        // Process trip
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
TNGetTripsByIdsRequestBuilder *builder = [client getTripsByIdsRequestWithTripIds:tripIds];
[builder assetWithAssetId:assetId assetContext:assetContext];
TNGetTripsByIdsRequest *request = [builder buildAndReturnError:&error];

TNGetTripsByIdsCall *call = [[TNGetTripsByIdsCall alloc] init];
[call executeWithRequest:request callback:^(TNGetTripsResponse *response, TNDriveMotionException *error) {
    for (BasicTrip *trip in response.trips) {
        // Process trip
    }
}];

Notes: - Maximum 50 trips per request in cloud mode - Vehicle-based only (requires asset() method) - Use excludeTripEvents() and excludeTripRoute() to optimize response size

Safety Score Version Support Improvements

Enhanced support for different safety score versions across multiple APIs: - TNGetAggregatedSafetyScoreRequest - TNGetContextualCoachingRequest (new) - TNPostContextualCoachingRequest (new) - TNGetEventPercentileTableRequest

1
2
3
4
5
6
let request = try builder
    .startDate(startDate)
    .endDate(endDate)
    .scoreVersion("V1.0.5")
    .asset(assetId: assetId, assetContext: assetContext)
    .build()

1
2
3
4
[builder startDate:startDate];
[builder endDate:endDate];
[builder scoreVersion:@"V1.0.5"];
[builder assetWithAssetId:assetId assetContext:assetContext];

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.