Skip to content

DriveMotionEnrollmentClient

The EnrollmentClient provide 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.

DriveMotion provides EnrollmentClient.

Get EnrollmentClient

1
2
3
4
5
    try {
        EnrollmentClient enrollmentClient = DriveMotionService.getEnrollmentClient();
    } catch (DriveMotionException e) {
        // The SDK is not initialized
    }

1
2
3
4
5
    try {
        val enrollmentClient: EnrollmentClient = DriveMotionService.getEnrollmentClient()
    } catch (e: DriveMotionException) {
        // The SDK is not initialized
    }

Use EnrollmentClient

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

Note

The client since SDK Version 2.12.0

Get launch auth flow result

Get Request Builder

1
    LaunchAuthFlowRequest.ByVinBuilder builder = enrollmentClient.getLaunchAuthByVinFlowRequest();

1
    val builder = enrollmentClient.getLaunchAuthByVinFlowRequest()

Build Request

LaunchAuthFlowRequest needs to set a VIN parameter.

1
2
    LaunchAuthFlowRequest request = builder.withVin(#VIN#)
                                .build();

1
2
    val request = builder.withVin(#VIN#)
                                .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
10
11
12
    Callback<LaunchAuthFlowResponse> callback = new Callback<LaunchAuthFlowResponse>() {

        @Override
        public void onSuccess(LaunchAuthFlowResponse uploadProgressResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<LaunchAuthFlowResponse> {
        override fun onSuccess(uploadProgressResponse: LaunchAuthFlowResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

This API retrieves currently connected and past paired peripherals (Bluetooth devices). Since 3.18.0, you can optionally set a vehicle asset on the request to merge the latest cloud Bluetooth recommendation (setup confidence, ranked devices) with the local list. Ordering is cloud first; on duplicate addresses the cloud copy wins. If the cloud call fails, the SDK returns local-only results (same as before).

Usage

Use getRecommendedPeripheralsRequest(), then optional withAsset(assetId, assetContext) (same semantics as link / replace: CAR = VIN, GLOBAL = channel client id), then build() and execute.

Kotlin example — local-only (unchanged)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
DriveMotionService.enrollmentClient
    .getRecommendedPeripheralsRequest()
    .build()
    .execute(object : Callback<GetRecommendedPeripheralsResponse> {
        override fun onSuccess(response: GetRecommendedPeripheralsResponse) {
            // response.peripherals, response.peripheralsFlow
        }
        override fun onFailure(throwable: Throwable) {
            // Handle the error
        }
    })

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
DriveMotionService.enrollmentClient
    .getRecommendedPeripheralsRequest()
    .withAsset(assetId, assetContext)
    .build()
    .execute(object : Callback<GetRecommendedPeripheralsResponse> {
        override fun onSuccess(response: GetRecommendedPeripheralsResponse) {
            // Merged list: response.peripherals
            // Optional: response.linkedPeripheral (LinkedPeripheralInfo: peripheral, confidenceLevel, matchedTripCount)
            // Optional: response.tripStatistics (RecommendationTripStatistics)
            // Peripherals may include confidence, connected trip counts, and cloud flag — see model Javadoc
        }
        override fun onFailure(throwable: Throwable) {
            // Handle the error
        }
    })

Response

The API returns a list of Bluetooth peripherals in peripherals, an optional hot peripheralsFlow, and when cloud merge is used and data is available, optional linkedPeripheral and tripStatistics as above.

This API links a specific peripheral device to a vehicle.

Usage

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

Kotlin Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
DriveMotionService.enrollmentClient
    .linkVehicleToPeripheralRequest()
    .withAsset(#assetId#, #assetContext#)
    .withPeripheral(#Peripheral#)
    .build()
    .execute(object : Callback<LinkVehicleToPeripheralResponse> {
        override fun onSuccess(response: LinkVehicleToPeripheralResponse) {
            // Handle the successful linking
        }
        override fun onFailure(throwable: Throwable) {
            // 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 (Peripheral): 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 ReplaceVehiclePeripheralRequest API.

Kotlin Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
DriveMotionService.enrollmentClient
    .replaceVehiclePeripheralRequest()
    .withAsset(#assetId#, #assetContext#)
    .withOldPeripheral(#Peripheral#)
    .withNewPeripheral(#Peripheral#)
    .build() 
    .execute(object : Callback<ReplaceVehiclePeripheralResponse> {
        override fun onSuccess(response: ReplaceVehiclePeripheralResponse) {
            // Handle the successful linking
        }
        override fun onFailure(throwable: Throwable) {
            // 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 (Peripheral): The old peripheral device to be replaced.
  • newPeripheral (Peripheral): 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 MigratePeripheralsRequest API.

Kotlin Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
DriveMotionService.enrollmentClient
    .migratePeripheralsRequest()
    .build()
    .execute(object : Callback<MigratePeripheralsResponse> {
        override fun onSuccess(response: MigratePeripheralsResponse) {
            // Handle the successful migration
        }
        override fun onFailure(throwable: Throwable) {
            // Handle the error
        }
    })

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). This supports enrollment flows that only know the peripheral name.

Usage

Use getMymByPeripheralRequest() on EnrollmentClient.

Kotlin example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
DriveMotionService.enrollmentClient
    .getMymByPeripheralRequest()
    .withPeripheralNames(listOf("Uconnect", "SYNC"))
    .build()
    .execute(object : Callback<GetMymByPeripheralResponse> {
        override fun onSuccess(response: GetMymByPeripheralResponse) {
            // response maps peripheral name to MYM list
        }
        override fun onFailure(throwable: Throwable) {
            // Handle error
        }
    })

Response

The response contains a map from peripheral name to a list of MYM records for that name.