Skip to content

Migration Guide 1.4

Migration SDK from old versions

This section will provide a detailed description of the API changes during the upgrade. We strongly recommend reading this documentation when upgrading the SDK version to understand the API differences and update your API calls accordingly based on the version disparities.

Migration to version 1.4.7

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 Event 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.

Migration to version 1.4.6

Update Analytics API: GetTrips: withExcludeTripEvents()

Starting from version 1.4.0, the GetTrips API will return the tripEvents list by default. However, this can result in more parsing time cost, especially when there are a large number of SafetyEvent objects. Additionally, displaying event details in a list view may not always be necessary.

To address this, a new parameter withExcludeTripEvents has been added to the GetTripsRequest. This allows the caller to control whether the tripEvents list should be included in the response or not. By default, the tripEvents list will not be returned. Set withExcludeTripEvents = false to include the tripEvents list in the response.

Migration to version 1.4.3

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 in-car, among others. To provide users with as much RGC information as possible, the SDK will validate the location labels returned in the GetTrips/GetTripDetail/GetLatestTripDetail 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.

Migration to version 1.4.2

Night Driving Statistics

SDK includes all the fields related to night time driving in the following objects:

1 TripInfo in GetTripDetailResponse:

  • 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 AggregatedScoreResponse and CumulativeScoreResponse:

  • 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).

Please note that only trips generated after this version(1.4.2) will have valid fields related to night time driving.

DriveMotionSettings: withAlertReceiverClazz()

DriveMotion SDK 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 DriveMotionSettings and add the corresponding receiver to receive the alerts using withAlertReceiverClazz(). This allows you to effectively inform users about potential safety concerns related to speeding incidents.

DriveMotionSettings: withPIIErasure()

To meet the requirements data anonymization, the external app can control the upload of device location information by setting PIIErasure option. By setting withPIIErasure = true, all latitude and longitude information included in the events uploaded to the server will be erasure. After anonymization, the server will only have access to approximate city-level information and will not be able to determine the precise location of the device. This ensures that sensitive location data is protected and only general information is accessible on the server.

DriveMotionClient: async start/stop drive call

DriveMotion SDK now supports asynchronous calls to startDriveRequest() and stopDriveRequest() by external apps under Manual mode. The SDK will invoke the callbacks based on the execution status of the Trip, specifically after the TripStartEvent and TripEndEvent 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    DriveMotionService.driveMotionClient.startDriveRequest().build()
            .execute(object : Callback<StartDriveResponse> {
                override fun onSuccess(response: StartDriveResponse?) {
                    // Start Drive successfully
                }

                override fun onFailure(t: Throwable?) {
                    // Start Drive meet exception t
                }
            })

Migration to version 1.4.1

DriveMotionSettings: withDeviceGuidOverrodeByForce()

New withDeviceGuidOverrodeByForce() has been added in DriveMotionSettings. It is used to indicate whether the SDK should forcefully use the device GUID specified in SDKOptions through setDeviceGuid() as the device identification code. By default, the app does not need to set this property, and the SDK will create a GUID based on the Android device information. However, if it is necessary for the in-car device to ensure that the app and SDK use the same fixed GUID, you can set this value to true.

DriveMotionSettings: withExternalUserIdUsedByForce()

New withExternalUserIdUsedByForce() has been added in DriveMotionSettings. 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 in-car device does not need to enable TelematicsUserId and wants to forcefully use the passed userId, you need to specify this value to true.

Warn

For app which using SDKBase SDKRuntime and requires user migrate:
Since DataConnector is a shared component and supports SDKRuntime and does not have the concept of user states, while DriveMotion's Trip and User are strongly related and do not support user switching, if you have a requirement for user migration, we recommend following the process outlined below:
1, stopDrive() to stop the current trip, if there is one trip in progress.
2, DriveMotionService.shutdown() to shutdown and exit current SDK session.
3, SDKRuntime.updateUserId() to switch the user.
4, DriveMotionService.initialize() with new user id in SDKOptions.
5, DriveMotionUtils.migrateUser() from previous user id to current new user id.

New UBI Client APIs

Support UBI client APIs in DriveMotionClient:

  • 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 DriveMotionUsersClient:

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

DataSourceClient: setDefaultSpeedLimit()

DriveMotion SDK supports the functionality for external apps to set a default speed limit value in situations where road info is unavailable. When road info is UNKNOWN, this default value will be used as the speed limit for events and scoring. The unit of measurement is meters per second (m/s), and the SDK's built-in default value is 80 miles per hour (mph).

1
2
    //  When initializing or when state change.
    DriveMotionService.dataSourceClient.setDefaultSpeedLimit(#DEFAULT_SPEED_LIMIT_IN_STATE_IN_METERS_PER_SECOND#)

Migration to version 1.4.0

Update Analytics API: GetTrips

To allow external apps to customize the querying of the Trip list, the GetTrips API has been modified as follows.
Please ensure you implement these modifications in your API calls to perform custom queries and obtain the desired results from the GetTrips API.

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. If the response's hasMore attribute is true, you need to make subsequent GetTrips requests by incrementing the offset value with pageIndex * limit until the hasMore attribute returns false.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
    val trips = arrayListOf<BasicTrip>()
    val page = intArrayOf(0)
    val hasMore = booleanArrayOf(true)
    while (hasMore[0]) {
        analyticsClient.getTripsRequest()
            .withStartDate(#REQUEST_START_DATE#)
            .withEndDate(#REQUEST_END_DATE#)
            .withLimit(limit)
            .withOffset(page[0] * limit)
            .build()
            .execute(object : Callback<GetTripsResponse> {
                override fun onSuccess(getTripsResponse: GetTripsResponse) {
                    trips.addAll(getTripsResponse.trips)
                    hasMore[0] = getTripsResponse.hasMore
                    // Render or Update page with trips list
                }

                override fun onFailure(throwable: Throwable) {
                    // Check error message
                }
            })
        page[0]++
    }

Note

Due to the presence of invalid trips, if you request a limit of 20 but receive 19 trips in the response and hasMore is true, there are still additional trips remaining utils response with hasMore is false.

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
    analyticsClient.getTripsRequest()
            .withStartDate(Date(0))
            .withEndDate(Date())
            .withLimit(1)
            .withOffset(0)
            .withSortBy(TripSortType.TRIP_START_TIME_ASC)
            .build()
            .execute(object : Callback<GetTripsResponse> {
                override fun onSuccess(getTripsResponse: GetTripsResponse) {
                    if (getTripsResponse.trips.isNotEmpty()) {
                        val firstTrip = getTripsResponse.trips[0]
                    } else {
                        // No valid trip
                    } 
                }

                override fun onFailure(throwable: Throwable) {
                    // Check error message
                }
            })

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, arrayOf(TransportationMode.BUS) represents the transportation mode as a bus, or arrayOf(TransportationMode.BIKE, TransportationMode.MOTORCYCLE) allows you to query trips of either bike or motorcycle types.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
    analyticsClient.getTripsRequest()
            .withStartDate(Date(0))
            .withEndDate(Date())
            .withLimit(100)
            .withOffset(0)
            .withTransportationModes(arrayOf(TransportationMode.BUS))
            .build()
            .execute(object : Callback<GetTripsResponse> {
                override fun onSuccess(getTripsResponse: GetTripsResponse) {
                    val busTrips = getTripsResponse.trips
                }

                override fun onFailure(throwable: Throwable) {
                    // Check error message
                }
            })