iOS

Prerequisite

Before integrating this module, ensure the following are in place:

• The DriveKit SDK is initialized and a user has been created.

• The Trip Analysis component is strongly recommended, as iBeacon detection is significantly enhanced during trip analysis — the scan mode is more efficient and the coverage range is greater.

Additionally, iBeacon and location detection require Always On exact location access, as well as the Location and Bluetooth sensors to be enabled on the device.

Integration

To add the Stolen Vehicle Locator module to your app using Swift Package Manager, add DriveKitStolenVehicleLocator from repository: https://github.com/DriveQuantPublic/drivekit-sdk-spm.git as dependency.

The Stolen Vehicle Locator module is available on iOS starting with DriveKit version 3.2.0.

Initialization

If you have disabled the SDK auto-initialization, an initialization phase is required to use the feature included in the Stolen Vehicle Locator module. In the application's AppDelegate file, import DriveKitStolenVehicleLocator:

import DriveKitStolenVehicleLocatorModule

Then, to initialize Stolen Vehicle Locator module in your app, you must call the initialization method in didFinishLaunchingWithOptions method of your AppDelegate file.

import DriveKitCoreModule
import DriveKitTripAnalysisModule
import DriveKitStolenVehicleLocatorModule

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    DriveKit.shared.initialize()
    ...
    DriveKitStolenVehicleLocator.shared.initialize()
    ...    
}

Configure UUIDs

The module scans for iBeacon proximity UUIDs.

Up to 5 UUIDs can be registered. UUIDs must be added one at a time.

UUIDs can be added or removed at any time — an active scan restarts automatically with the updated list.

iOS enforces a hard limit of 20 regions (UUIDs) per app, shared across all sources. To preserve this capacity for other uses within your app, the Stolen Vehicle Locator component limits the number of registered UUIDs to 5.

Add a UUID

Registers a new UUID in the scan list.

public func addUuid(_ uuid: String, completion: @escaping (_ result: DKAddUuidResult) -> Void)

It takes an uuid parameter in String format, and triggers a callback which is a Swift enum named DKAddUuidResult with associated values:

Value	Description
success	UUID is valid and added to the list.
error(DKAddUuidErrorType)	UUID could not be added. See error type below.

DKAddUuidErrorType

Value	Description
driveKitNotInitialized	DriveKit has not been initialized yet.
invalidUuidFormat	The provided UUID has an invalid format.
uuidAlreadyAdded	This UUID is already in the list.
totalUuidLimitReached	The 5-UUID maximum has been reached.

• Only the UUID is required — no Major or Minor values are needed. Stolen vehicle management is handled entirely server-side: once a smartphone detects a beacon matching a monitored UUID, the backend cross-references the beacon's Major and Minor values to identify the vehicle and trigger the appropriate alerts.

• UUIDs must follow the standard format defined by Apple for iBeacon proximity regions: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12 hexadecimal characters, separated by hyphens). See Apple's CLBeacon.uuid documentation for details.

• Letters must be lowercase. If uppercase letters are provided, they will be automatically converted before the UUID is stored.

Remove a UUID

Removes a UUID from the scan list. If the list becomes empty, scanning stops automatically.

public func removeUuid(_ uuid: String, completion: @escaping (_ result: DKRemoveUuidResult) -> Void)

It takes an uuid parameter in String format, and triggers a callback which is a Swift enum named DKRemoveUuidResult with associated values:

Value	Description
success	UUID is valid and removed from the list.
error(DKRemoveUuidErrorType)	UUID could not be added. See error type below.

DKRemoveUuidErrorType

Value	Description
driveKitNotInitialized	DriveKit has not been initialized yet.
invalidUuidFormat	The provided UUID has an invalid format.
uuidNotFound	This UUID is not in the list.

Get the UUID list

Retrieves the current list of registered UUIDs.

public func getUuids(completion: @escaping (_ result: DKGetUuidListResult) -> Void)

Returns a DKGetUuidListResult enum via callback:

Value	Description
success([String])	UUID list retrieved successfully. The array may be empty if no UUIDs have been registered.
error(DKGetUuidListErrorType)	List could not be retrieved. See error type below.

DKGetUuidListErrorType

Value	Description
driveKitNotInitialized	DriveKit has not been initialized yet.

Configure iBeacon search

Enable iBeacon search

Enable the search for iBeacon signals matching the registered UUID list.

public func enableScan(completion: @escaping (_ result: DKEnableScanResult) -> Void)

DKEnableScanResult

Value	Description
success	Scan successfully enabled.
error(DKEnableScanErrorType)	Scan could not be enabled. See error type below.

DKEnableScanErrorType

Value	Description
driveKitNotInitialized	DriveKit has not been initialized yet.
userNotConnected	No authenticated user found.
scanAlreadyEnabled	The scan has already been enabled.

Disable iBeacon search

Disable the search for iBeacon signals matching the registered UUID list.

public func disableScan(completion: @escaping (_ result: DKDisableScanResult) -> Void)

DKDisableScanResult

Value	Description
success	Scan successfully enabled.
error(DKDisableScanErrorType)	Scan could not be enabled. See error type below.

DKDisableScanErrorType

Value	Description
driveKitNotInitialized	DriveKit has not been initialized yet.
userNotConnected	No authenticated user found.
scanAlreadyDisabled	The scan has already been disabled.