Migration Guide 1.4

Migration SDK from old versions

This section provides a comprehensive description of the API changes that occur during the upgrade. It is highly recommended to review this documentation when upgrading the SDK version in order to understand the differences in the API and make the necessary updates to your API calls according to the version disparities.

Migration to version 1.4.3

Support Event Explanation

In order to describe the reasons for event occurrence, DriveMotion SDK has added the following fields to provide more detailed information about the event. You can use the relevant fields to explain the event.

In the DMEvent object:

• The new field eventDistance describes the distance traveled during the event (in meters).
• The new field eventDuration describes the duration of the event (in seconds).
• The new field eventDeltaChange describes the change in units for the event (the unit varies depending on the specific event type, please refer to the specific event documentation, for example, the unit for hard acceleration is meters per second of speed change).
• The new field eventReason describes the reason for the event occurrence (in English). You can choose to use eventReason or construct the description of the reason using one or more of the aforementioned fields.

In each EventItem object:

• The new field itemDistance describes the distance traveled during the event item (in meters).
• The new field itemDuration describes the duration of the event item(in seconds).
• The new field itemSpeedLimit describes the speed limit during the event item (in meters per second).
• The new field itemReason describes the reason for the event item occurrence (in English). You can choose to use eventReason or construct the description of the reason using one or more of the aforementioned fields.

Analytics APIs with RGC

In certain situations, the start or end points of a trip may not include valid street information. These situations can include under offline mode, temporary network issues, forcefully stopped trips, app killed without trip stop, among others. To provide users with as much RGC information as possible, the SDK will validate the location labels returned in the TNGetTripsCall/TNGetTripDetailCall/TNGetLatestTripDetailCall responses. If necessary, the SDK will attempt to update the RGC information. This process may result in a temporary slowdown in the response time as the SDK performs the necessary operations to update the RGC information. The aim is to enhance the user interface by including accurate and up-to-date location details and avoid display latitude and longitude information to user.

New in analytics api(TNGetTripsCall): excludeTripEvents

Starting from version 1.4.0, the TNGetTripsCall API include the tripEvents list in the response by default. However, in scenarios where there is a large number of SafetyEvent data or when displaying event details in a list view is unnecessary, this default behavior can result in increased parsing time.

To address this, a new parameter called excludeTripEvents has been added in the TNGetTripsRequest. This parameter provides control over whether the tripEvents list should be included in the response or not. By default, the tripEvents list will not be returned. To include the tripEvents list in the response, you can set excludeTripEvents to false.

By the excludeTripEvents parameter, you can optimize the response parsing time and reduce unnecessary data retrieval when it's not required.

Migration to version 1.4.2

Night Driving Statistics

Includes all the fields for night driving in the following objects:

1 TNTripInfo in TNGetTripDetailResponse:

• movingDuration to indicate the trip moving duration (gps speed is larger than 0) in seconds.
• nightDuration to indicate the trip night duration in seconds (local time 10pm - 4am).
• nightMovingDuration to indicate the trip night moving duration (gps speed is larger than 0) in seconds (local time 10pm - 4am).
• nightDistance to indicate the trip night distance in meters (local time 10pm - 4am).

2 TripsInfo in TNAggregatedScoreResponse and TNCumulativeScoreResponse:

• totalMovingDuration to indicate the total trip moving duration (gps speed is larger than 0) in seconds.
• totalNightDuration to indicate the total trip night duration in seconds (local time 10pm - 4am).
• totalNightMovingDuration to indicate the total trip night moving duration (gps speed is larger than 0) in seconds (local time 10pm - 4am).
• totalNightDistance to indicate the total trip night distance in meters (local time 10pm - 4am).

Note

Only trips generated after this version(1.4.2) will have valid fields for night driving.

New in TNDriveMotionSettings: alertDetegate

DriveMotion SDK now supports handling SafetyAlert events (specifically supports the SpeedingAlert event), which sends a notification when the vehicle exceeds the speed limit to reduce the likelihood of dangerous incidents. If you need to notify users of these alert events, you can modify TNDriveMotionSettings and add the corresponding receiver to receive the alerts using alertDetegate. This allows you to effectively inform users about potential safety concerns related to speeding incidents.

Update start/stop drive call in async

DriveMotion SDK now supports asynchronous calls to startDriveRequest() and stopDriveRequest() by external apps on Manual mode. The SDK will invoke the callbacks based on the execution status of the Trip, specifically after the TNTripStartEvent and TNTripEndEvent have occurred. This allows for more flexibility in starting and stopping trips while ensuring that the necessary events are captured and processed by the SDK.

Swift

    let request = driveMotionClient.stopDriveRequest().build()
    TNStopDriveCall().execute(request: request) { response, error in
       if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

Objective-C

    TNStopDriveRequest* request = [[driveMotionClient stopDriveRequest] build];
    TNStopDriveCall* call = [[TNStopDriveCall alloc]init];
    [call executeWithRequest:request callback:^(TNStopDriveResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Migration to version 1.4.1

New in TNDriveMotionSettings: isExternalUserIdUsedByForce

The isExternalUserIdUsedByForce has been added in TNDriveMotionSettings. Under the new UBI process, the DriveMotion SDK will use a TelematicsUserId to replace the userId passed by the app as the internal UserId within the SDK. However, if the user does not need to enable TelematicsUserId and wants to forcefully use the passed userId, you need to specify this value to true.

New UBI Client APIs

Support UBI client APIs in TNDriveMotionClient:

• startDriveDetectionRequest(): to start drive detection after user opt in.
• stopDriveDetectionRequest(): to sop drive detection after user opt out.
• getDriveDetectionStateRequest(): to get current detection state.

Support UBI client APIs in TNDriveMotionUsersClient:

• getUserProfileRequest(): for get user profile info.
• optInRequest(): for user opt in.
• optOutRequest(): for user opt out.
• deleteAccountAndDataRequest(): for delete account and data.

Migration to version 1.4.0

Update initialize/shutdown sdk in async

DriveMotion SDK now supports asynchronous initialization and shutdown, the original ones is deprecated and will be removed in subsequent versions.

Swift

    TNDriveMotionService.initialize(sdkOptions: options, driveMotionSettings: settings) { result, error in
        if result {
            // Initialize success
        } else {
            // The SDK initialization failed. Please check the message of DriveMotionException and perform subsequent operations according to the message.
        }
    }

Objective-C

    [TNDriveMotionService initializeWithSdkOptions:options
                            driveMotionSettings:settings
                                        handler:^(BOOL result, TNDriveMotionException * _Nullable error) {
        if (result) {
            // Initialize success
        } else {
            // The SDK initialization failed. Please check the message of DriveMotionException and perform subsequent operations according to the message.
        }
    }];

Note

Some model classes have been moved to the TelenavDriveMotionAPI dependency library and no longer exist in the current compilation. If you are unable to locate them, please import TelenavDriveMotionAPI into your implementation.

Update analytics api in async with callback

Analytics apis(TNAggregatedScoreCall, TNGetLiveTripDetailCall, TNGetTripDetailCall, TNGetLatestTripDetailCall, TNGetConfigDescriptionsCall, TNGetCumulativeScoreCall, TNGetTripsCall, TNUpdateTripTransportationModeCall) now support asynchronous return data, but keep the original calls without change, because asynchronous is done in the SDK internal processing.

Update analytics api: TNGetTripsCall

To allow external callers to customize queries of trip list, it is essential to incorporate these changes into your API calls to execute custom queries and obtain the desired results from the GetTrips API. The changes as follows:

Parameters Update:

• Add sortBy parameter to perform custom queries with sorting.
• Add transportationModes to perform custom queries with filtering.
• The default value of the limit parameter has been changed to 20, with a valid range of 0 to 100.

To use these modifications:

1、To query all trips within a specified range:

Pass the desired startDate and endDate parameters for trips. If the response has a hasMore attribute is true, need to make subsequent GetTrips requests until the hasMore attribute becomes false. This ensures you retrieve all available data in a paginated manner.

Swift

    let builder = driveMotionAnalyticsClient.getTripsRequest()
    let request = builder.startDate(#startDate#)
                        .endDate(#endDate#)
                        .offset(#offset#)
                        .build()
    let call = TNGetTripsCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
        // if response.hasMore = true, continue to request subsequent trips with the offset of the current trip count, otherwise, all trips are retrieved
        }
        if let error = error {
        // Handle error
        }
    }

Objective-C

    TNGetTripsRequestBuilder *builder = [driveMotionAnalyticsClient getTripsRequest];
    [builder startDate:#startDate#];
    [builder endDate:#endDate#];
    [builder offset:#offset#];
    TNGetTripsRequest *request = [builder build];
    TNGetTripsCall *call = [TNGetTripsCall new];
    [call executeWithRequest:request callback:^(TNGetTripsResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
        // if response.hasMore = true, continue to request subsequent trips with the offset of the current trip count, otherwise, all trips are retrieved
        }
        if (error) {
        // Handle error
        }
    }];

2、To query the first trip details for a user:

To query user's first trip, passing limit = 1 and orderBy = TripSortType.tripStartTimeASE, this will return the first finished trip info, or nothing when no valid trips.

Swift

    let builder = driveMotionAnalyticsClient.getTripsRequest()
    let request = builder.startDate(#startDate#)
                        .endDate(#endDate#)
                        .limit(1)
                        .offset(0)
                        .sortType(#TripSortType.tripStartTimeASE#)
                        .build()
    ...

Objective-C

    TNGetTripsRequestBuilder *builder = [driveMotionAnalyticsClient getTripsRequest];
    [builder startDate:#startDate#];
    [builder endDate:#endDate#];
    [builder limit:1];
    [builder offset:0];
    [builder sortType:TripSortTypeTripStartTimeASE];
    ...

3、To query trips of specified transportation type:

Pass request transportation mode as the value for the "transportationModes" parameter. You can specify one or multiple transportation modes by using an array. For example, [TNTransportationMode.BUS] represents the transportation mode as a bus, or [TNTransportationMode.BIKE, TNTransportationMode.MOTORCYCLE] allows you to query trips of either bike or motorcycle types.

Note

Due to transportation mode stored in the database is the string type, the array type passed in by the query must be a string. The string values corresponding to all tranportation mode: 'DRIVER'、'PASSENGER'、'TRAIN'、'AIRPLANE'、'BIKE'、'BOAT'、'BUS'、'MOTORCYCLE'、'FOOT'、'OTHER'.

Swift

    let builder = driveMotionAnalyticsClient.getTripsRequest()
    let request = builder.startDate(#startDate#)
                        .endDate(#endDate#)
                        .offset(0)
                        .transportationModes(["BUS"])
                        .build()
    ...

Objective-C

    TNGetTripsRequestBuilder *builder = [driveMotionAnalyticsClient getTripsRequest];
    [builder startDate:#startDate#];
    [builder endDate:#endDate#];
    [builder offset:0];
    [builder transportationModes:@["BUS"]];
    ...