Android

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.

Furthermore, iBeacon detection and location retrieval require the following runtime permissions:

• Precise and background location permissions

• Nearby devices permission

The feature also requires the Location and Bluetooth sensors to be enabled.

Integration

Add the following dependency to your app-level build.gradle:

dependencies {
implementation 'com.drivequant.drivekit:drivekit-stolen-vehicle-locator:$drivekit_version
}

The Stolen Vehicle Locator module is available on Android starting with DriveKit version 3.1.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. To initialize the Stolen Vehicle Locator component in your app, you must call the initialization method in the onCreate method of your Application class.

DriveKitStolenVehicleLocator
fun 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.

Add a UUID

Registers a new UUID in the scan list.

fun addUuid(uuid: String, callback: (DKAddUuidResult) -> Unit)

It takes an uuid parameter in String format, and triggers a callback which is sealed class named DKAddUuidResult:

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

DKAddUuidErrorType

Value	Description
DRIVEKIT_NOT_INITIALIZED	DriveKit has not been initialized yet.
INVALID_UUID_FORMAT	The provided UUID has an invalid format.
UUID_ALREADY_ADDED	This UUID is already in the list.
TOTAL_UUID_LIMIT_REACHED	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.

fun removeUuid(uuid: String, callback: (DKRemoveUuidResult) -> Unit)

DKRemoveUuidResult

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

DKRemoveUuidErrorType

Value	Description
DRIVEKIT_NOT_INITIALIZED	DriveKit has not been initialized yet.
INVALID_UUID_FORMAT	The provided UUID has an invalid format.
UUID_NOT_FOUND	This UUID is not in the list.

Get the UUID list

Retrieves the current list of registered UUIDs.

fun getUuids(callback: (DKGetUuidListResult) -> Unit)

Returns a DKGetUuidListResult sealed class via callback:

Value	Description
Success(val uuids: List)	UUID list retrieved successfully. The list may be empty if no UUIDs have been registered.
Error(val error: DKGetUuidListErrorType)	List could not be retrieved. See error type below.

DKGetUuidListErrorType

Value	Description
DRIVEKIT_NOT_INITIALIZED	DriveKit has not been initialized yet.

Configure iBeacon search

Enable iBeacon search

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

fun enableScan(callback: (DKEnableScanResult) -> Unit)

DKEnableScanResult

Value	Description
Ssuccess	Scan successfully enabled.
Error(val error: DKEnableScanErrorType)	Scan could not be enabled. See error type below.

DKEnableScanErrorType

Value	Description
DRIVEKIT_NOT_INITIALIZED	DriveKit has not been initialized yet.
USER_NOT_CONNECTED	No authenticated user found.
SCAN_ALREADY_ENABLED	The scan has already been enabled.

Disable iBeacon search

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

fun disableScan(callback: (DKDisableScanResult) -> Unit)

DKDisableScanResult

Value	Description
Success	Scan successfully enabled.
Error(val error: DKDisableScanErrorType)	Scan could not be enabled. See error type below.

DKDisableScanErrorType

Value	Description
DRIVEKIT_NOT_INITIALIZED	DriveKit has not been initialized yet.
USER_NOT_CONNECTED	No authenticated user found.
SCAN_ALREADY_DISABLED	The scan has already been disabled.