Skip to content

DriveMotionEnrollmentClient

DriveMotion provides TNEnrollmentClient. It provides the following APIs, such as: launch authentication flow (SmartCar), get recommended peripherals (BT list), link peripheral to vehicle, replace a vehicle's peripheral with a new peripheral, auto migrate existing peripherals for vechiles to a new phone.

Get TNEnrollmentClient

1
2
3
4
5
    do {
        let driveMotionAnalyticsClient = try TNDriveMotionService.getEnrollmentClient()
    } catch {
        // The SDK is not initialized
    }

1
2
3
4
5
    NSError *error;
    TNDriveMotionAnalyticsClient *client = [TNDriveMotionService getEnrollmentClientWithError:&error];
    if (error) {
        // The SDK is not initialized
    }

Use TNEnrollmentClient

TNEnrollmentClient provides the the authorization flow result by Vehicle Identification Number (VIN)

Note

The client since SDK Version 2.12.0

Launch Auth Flow By VIN

Get Request Builder

1
    let builder = enrollmentClient.getLaunchAuthFlowByVinRequest()

1
    TNLaunchAuthFlowRequestByVinBuilder *builder = [[enrollmentClient getLaunchAuthFlowByVinRequest] build];

Build Request

TNLaunchAuthFlowRequest needs to pass VIN parameter. 

1
2
    let request = builder.vin(#VIN#)
                         .build()

1
2
    [builder vin:#VIN#];
    TNLaunchAuthFlowRequest *request = [builder build];

Create a Call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNLaunchAuthFlowCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNLaunchAuthFlowCall *call = [TNLaunchAuthFlowCall new];
    [call executeWithRequest:request callback:^(TNLaunchAuthFlowResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

This API retrieves currently connected or once connected peripherals (Bluetooth devices). Since 3.18.0, you can optionally pass a vehicle asset (VIN or channel client id) to merge the latest cloud recommendation with the local list (cloud-first order; cloud wins on duplicates; if the cloud call fails, the SDK falls back to local-only).

Usage

To fetch the recommended peripherals, use getRecommendedPeripheralsRequest() and TNGetRecommendedPeripheralsRequest.

Swift example (local-only, same as before)

Omit asset(_:_:) to keep local recommendations only (no cloud request).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
let request = try TNDriveMotionService.getEnrollmentClient()
    .getRecommendedPeripheralsRequest()
    .build()

TNGetRecommendedPeripheralsCall().execute(request: request) { response, error in
    if let response = response {
        // response.peripherals
    } else if let error = error {
        // Handle the error
    }
}

Swift example — cloud merge and setup confidence (since 3.18.0)

Call asset(_ assetId: String, _ assetContext: AssetContext) on the builder before build() (same asset semantics as link / replace: .car for VIN, .global for channel client id). The merged list is still in response.peripherals. When cloud data is present, the response may also include linkedPeripheral (TNLinkedPeripheralInfo: peripheral, TNPeripheralConfidenceLevel, matched trip count) and tripStatistics (TNPeripheralRecommendationTripStatistics). Individual entries may expose confidence, connectedTripCount, and isCloudRecommended on TNPeripheral.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
let request = try TNDriveMotionService.getEnrollmentClient()
    .getRecommendedPeripheralsRequest()
    .asset(channelClientId, .global) // or VIN with .car
    .build()

TNGetRecommendedPeripheralsCall().execute(request: request) { response, error in
    if let response = response {
        // response.peripherals, response.linkedPeripheral, response.tripStatistics
    } else if let error = error {
        // Handle the error
    }
}

Swift example — Combine publisher (since 3.18.0)

TNGetRecommendedPeripheralsCall().execute(request:) (the overload with no callback) returns a Combine publisher that delivers the merged response for the same request first, then re-runs that request when connected peripherals change.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
let request = try TNDriveMotionService.getEnrollmentClient()
    .getRecommendedPeripheralsRequest()
    .asset(channelClientId, .global)
    .build()
let subscription = TNGetRecommendedPeripheralsCall().execute(request: request)
    .sink(
        receiveCompletion: { completion in
            switch completion {
            case .finished:
                break
            case .failure(let error):
                // Handle the error
                break
            }
        },
        receiveValue: { response in
            // Merged recommended peripherals
        }
    )
subscription?.cancel()

Response

The API returns a list of Bluetooth peripherals in peripherals, plus the optional cloud metadata above when an asset is set and cloud data is available.

This API links a specific peripheral device to a vehicle.

Usage

To link a peripheral to a vehicle, use the TNLinkVehicleToPeripheralRequest API.

Swift Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
let request = try TNDriveMotionService.getEnrollmentClient()
    .linkVehicleToPeripheral()
    .asset(#assetId#, #assetContext#)
    .peripheral(#Peripheral#)
    .build()

TNLinkVehicleToPeripheralCall().execute(request: request) { response, error in
    if let response = response {
        // Handle the successful linking
    } else if let error = error {
        // Handle the error
    }
}

Parameters

  • assetId (String): Vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext).
  • assetContext (Enum(car,global)): Context for assetId, if is "car", assetId value should be VIN, otherwise assetId should be Channel client id.
  • peripheral (TNPeripheral): The peripheral device being linked to the vehicle.

Response

The API confirms whether a peripheral was successfully linked to a vehicle.

Replace Vehicle Peripheral (since 2.18.0)

This API replaces an old peripheral with a new one for a specific vehicle.

Usage

To replace a vehicle's peripheral, use the TNReplaceVehiclePeripheralRequest API.

Swift Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
let request = try TNDriveMotionService.getEnrollmentClient()
    .replaceVehiclePeripheral()
    .asset(#assetId#, #assetContext#)
    .oldPeripheral(#Peripheral#)
    .newPeripheral(#Peripheral#)
    .build()

TNReplaceVehiclePeripheralCall().execute(request: request) { response, error in
    if let response = response {
        // Handle the successful replacement
    } else if let error = error {
        // Handle the error
    }
}

Parameters

  • assetId (String): Vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext).
  • assetContext (Enum(car,global)): Context for assetId, if is "car", assetId value should be VIN, otherwise assetId should be Channel client id.
  • oldPeripheral (TNPeripheral): The old peripheral device to be replaced.
  • newPeripheral (TNPeripheral): The new peripheral device replacing the old one.

Response

The API confirms whether the peripheral replacement is successful.

Migrate Peripherals (since 2.19.0)

This API is to migrate the existing mapping relationship (peripheral, vehicle) to a new phone.

Usage

To migrate peripherals, use the TNMigratePeripheralsRequest API.

Swift Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
let request = try TNDriveMotionService.getEnrollmentClient()
    .migratePeripheralsRequest()
    .build()

TNMigratePeripheralsCall().execute(request: request) { response, error in
    if let response = response {
        // Handle the successful migration
    } else if let error = error {
        // Handle the error
    }
}

Parameters

  • No

Response

The API confirms whether the migration of the existing mapping relationship is successful.

Get MYM by peripheral name (since 3.16.0)

Queries the cloud for vehicle make, year, and model (MYM) entries associated with one or more Bluetooth peripheral names (for example Uconnect or SYNC).

Swift example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
let request = try TNDriveMotionService.getEnrollmentClient()
    .getMymByPeripheralRequest()
    .peripheralNames(["Uconnect", "SYNC"])
    .build()

TNGetMymByPeripheralCall().execute(request: request!) { response, error in
    if let response = response {
        // response.mymMap: [String: [TNVehicleMakeYearModel]]
    } else if let error = error {
        // Handle error
    }
}

Response

The response exposes a map from peripheral name to an array of TNVehicleMakeYearModel values.