Vehicle management

DriveKit Vehicle component manages cars and trucks vehicles.

Methods presented in this part are available in the DriveKitVehicle class

Create a custom vehicle

It is possible to create a custom vehicle from your own data. Create your vehicle using the method:

func createCustomVehicle(
    characteristics: DKVehicleCharacteristics,
    name: String? = nil,
    id: String,
    completionHandler: @escaping (DKVehicleManagerStatus, DKVehicle?) -> Void
)

Each vehicle will have a unique identifier and this unique ID will be added into the trip synchronization response.

This method have the following parameters:

Name	Type	Description
characteristics	DKVehicleCharacteristics	Characteristics of the vehicle you want to create. Model is detailed in the References part.
name	String	The name of the vehicle you want to create
id	String	The unique identifier of the vehicle you want to create

Check the DKVehicleManagerStatus value to ensure your vehicle is correctly created:

Value	Description
success	Vehicle is successfully created and saved in the local database.
invalidCharacteristics	Vehicle is not created and not saved in the local database because provided characteristics are not valid.
vehicleIdAlreadyUsed	Vehicle is not created and not saved in the local database because the provided vehicleId already exists.
onlyOneGpsVehicleAllowed	This value is not returned for this service.
error	Vehicle is not created and not saved in the local database because there was an unexpected error. e.g: User not logged to DriveKit

DKVehicle model is described in the References part.

Synchronize vehicle list

You can retrieve the user’s vehicle list from the DriveQuant servers by calling the following method:

func getVehiclesOrderByNameAsc(
    type: DKVehicleSynchronizationType = .defaultSync, 
    completionHandler: @escaping (DKVehicleSyncStatus, [DKVehicle]) -> Void
) 

This method have the following parameter:

Name	Type	Description
type	DKVehicleSynchronizationType	Can be defaultSync or cache. - defaultSync will synchronize the vehicles by calling the DriveQuant servers - cache will retrieve the vehicles already synchronized in the local database.

DKVehicleSyncStatus and DKVehicle models are described in the References part.

Retrieve local vehicle list

You can retrieve the list of vehicles stored in the DriveKit local database by calling the previous method but with the type parameter to .cache.

Replace a vehicle

Instead of deleting and then creating a new vehicle, you can use only one method to replace an existing vehicle.

A previously paired beacon to that vehicle is automatically paired to the new vehicle.

Replace a car

func replaceWithCarVehicle(
        oldVehicleId: String,
        characteristics: DKCarVehicleCharacteristics,
        name: String? = nil,
        liteConfig: Bool = false,
        completionHandler: @escaping (DKVehicleReplaceStatus, DKVehicle?) -> Void
)

This method have the following parameters:

Name	Type	Description
oldVehicleId	String	The unique identifier of the car you want to replace
characteristics	DKCarVehicleCharacteristics	Characteristics of the car you want to create
name	String	The name of the car
liteConfig	Boolean	Advanced configuration. Leave this parameter as false.

DKVehicleReplaceStatus and DKVehicle models are described in the References part.

Replace a truck

func replaceWithTruckVehicle(
        oldVehicleId: String,
        characteristics: DKTruckVehicleCharacteristics,
        name: String? = nil,
        completionHandler: @escaping (DKVehicleReplaceStatus, DKVehicle?) -> Void
)

This method have the following parameters:

Name	Type	Description
oldVehicleId	String	The unique identifier of the truck you want to replace
characteristics	DKTruckVehicleCharacteristics	Characteristics of the truck you want to create
name	String	The name of the truck

DKVehicleReplaceStatus and DKVehicle models are described in the References part.

Delete a vehicle

When you delete a vehicle, a previously paired beacon or Bluetooth device to that vehicle is automatically unpaired and released from the vehicle. By this way, you can immediately pair the beacon or the Bluetooth device to another vehicle.

To delete a vehicle, you have to call the following method:

func deleteVehicle(
    vehicleId: String,
    completionHandler: @escaping (DKVehicleManagerStatus) -> Void
)

This method have the following parameter:

Name	Type	Description
vehicleId	String	The identifier of the vehicle that you want to delete.

Check the DKVehicleManagerStatus value to ensure your vehicle is successfully deleted:

Value	Description
success	Vehicle is successfully deleted and changes are saved in the local database.
unknownVehicle	The specified vehicle could not be deleted because the vehicle id is not a vehicle or belongs to another user account.
invalidCharacteristics	This value is not returned for this service.
vehicleIdAlreadyUsed	This value is not returned for this service.
onlyOneGpsVehicleAllowed	This value is not returned for this service.
error	Vehicle is not deleted and changes are not saved in the local database because there was an unexpected error. e.g: No network

Rename a vehicle

To rename a vehicle, you have to call the following method:

func renameVehicle(
    name: String,
    vehicleId: String,
    completionHandler: @escaping (DKVehicleManagerStatus) -> Void
) 

This method have the following parameters:

Name	Type	Description
name	String	The new name for the vehicle
vehicleId	String	The identifier of the vehicle that you want to rename

Check the DKVehicleManagerStatus value to ensure your vehicle is successfully deleted:

Value	Description
success	Vehicle is successfully renamed and changes are saved in the local database.
unknownVehicle	The specified vehicle could not be renamed because the vehicle id is not valid.
invalidCharacteristics	This value is not returned for this service.
vehicleIdAlreadyUsed	This value is not returned for this service.
onlyOneGpsVehicleAllowed	This value is not returned for this service.
error	Vehicle is not renamed and changes are not saved in the local database because there was an unexpected error. e.g: No network

Change the detection mode of a vehicle

When you have a vehicle, it is necessary to set its DetectionMode type. The following function is used to select the DetectionMode of a vehicle:

func updateDetectionMode(
    vehicleId: String,
    detectionMode: DKDetectionMode,
    forceGPSVehicleUpdate: Bool = false,
    completionHandler: @escaping (DKDetectionModeStatus) -> Void
)

This method have the following parameters:

Name	Type	Description
vehicleId	String	The vehicle which you want to update the DetectionMode
detectionMode	DKDetectionMode	The detection mode you want for the vehicle
forceGPSVehicleUpdate	Boolean	Optional parameter to force the GPS detection mode for a new vehicle if there is already a vehicle with this mode. The default setting is false. In this case, the response of this service request will be gpsModeAlreadyExists and the new vehicle will not be configured in GPS mode. If this setting is true, the vehicle will inherit the GPS trigger mode and the existing vehicle that had this mode will be switched to the .disabled mode.

DKDetectionModeStatus model is described in the References part.

Information: If a driver has more than one vehicle, only one can be configured in GPS mode. If you choose a GPS trigger mode for a vehicle while there is already another vehicle with this trigger mode, then you must specify the appropriate action with the forceGPSVehicleUpdate parameter to true. The other vehicle will have its detection mode updated to .disabled.

Get Vehicle Last Location

This function returns the location of the end of the last trip for a given vehicle.

The returned location type is DKTripLocation

To retrieve the location at which the last recorded trip for the vehicle ended, use the following method:

func getVehicleLocation(_ vehicleId: String) -> DKTripLocation?

Get Vehicle Timeline

Each time a trip is analyzed for a given vehicle, some data are aggregated in its timeline.

To get the timeline for a given vehicle, you have to call the following method:

public func getTimeline(
        vehicleId: String,
        periods: [DKPeriod],
        type: SynchronizationType = .defaultSync,
        completionHandler: @escaping (TimelineSyncStatus, [DKVehicleTimeline]?) -> Void)

This method have the following parameters:

Name	Type	Description
vehicleId	String	The unique identifier of the driver’s vehicle.
periods	[DKPeriod]	Get timeline data in a specific period of time. Possible values are : .week, .month, .year
synchronizationType	SynchronizationType	Define the source of the timelines data you want to retrieve. Possible values are: .cache: No sync will be performed and the data retrieved during the last sync will be returned via the completionHandler. .defaultSync: the SDK will try to synchronize timelines with DriveQuant backend and then return them via the completionHandler.

The TimelineSyncStatus enum values are:

Value	Description
success	Synchronization has been successfully performed
drivekitNotInitialized	DriveKit has not been initialized yet.
userNotConnected	No authenticated user was found.
vehicleNotFound	The identifier of the vehicle passed as parameter is not associated with any of the user's vehicles.
timelineNotFound	There was no timeline for the related vehicle. This rare situation occurs only if the vehicle was created several years ago and has not yet analyzed trips.
cacheDataOnly	SynchronizationType has been set to .cache.
failedToSyncTimelineCacheOnly	Synchronization has failed, only data retrieved during the last sync are returned.

The second argument in the completionHandler is a list of DKVehicleTimeline object, one per requested period.

DKVehicleTimeline model is described in the References part.