Beacon usage

Configure beacons

The automatic trip detection feature is compliant with iBeacon Bluetooth beacons. A beacon is a Bluetooth low energy (BLE) device that broadcasts a universally unique identifier. This signal can be detected by the SDK and used to trigger the trip analysis.

In addition, the beacon is a smart and cost-effective solution for identifying the vehicle in which the driver is travelling.

The DriveKit SDK is fully compatible with the Apple iBeacon™ standard.

You can add beacon identifiers to Trip Analysis SDK by calling the following method:

DriveKitTripAnalysis.shared.setBeacons(beacons: [BeaconData])

A detailed description of BeaconData class is available here.

Beacons can have 3 configurations:

• Only proximityUuid: All beacons with this proximityUuid value can start a trip (independently from major and minor value).

  • BeaconData(proximityUuid: String)

• ProximityUuid + major: All beacons with this proximityUuid and major values can start a trip (independently from minor value).

  • BeaconData(proximityUuid: String, major: Int)

• ProximityUuid + major + minor: All beacons with this proximityUuid, major and minor values can start a trip.

  • BeaconData(proximityUuid: String, major: Int, minor: Int)

Since iOS13, iOS beacon functions have some limitations, therefore all configured beacons must have the same proximity UUID.

If you want to remove beacons from SDK configuration, just call the method with an empty array.

On iOS, there is a limitation of 20 regions (including beacons) that can be monitored. Consequently, make sure that you limit to the minimum the number of beacons configured in the SDK.

"Regions are shared resources that rely on specific hardware capabilities. To ensure that all apps can participate in region monitoring, Core Location prevents any single app from monitoring more than 20 regions simultaneously." developer.apple.com

Beacon required

To avoid the recording of unwanted trips (trips performed outside the vehicle where the beacon is placed), it is possible to automatically cancel the trip if the beacon is not "seen" several times during the trip. Generally, a trip will be cancelled in less than 6 minutes if the beacon is not in the vehicle.

By default, this setting is disabled, but you can enable it by calling the following method:

DriveKitTripAnalysis.shared.setBeaconRequired(required: true)

To disable this settings, call the same method with the parameter set to false

DriveKitTripAnalysis.shared.setBeaconRequired(required: false)

If you have configured the beacon and the bluetooth device as required, trips will be recorded if at least a beacon or a bluetooth device is detected during the trip.

Filter the beacon trigger to start trip recording

In very rare cases, it may be useful to avoid trip detection using the beacon but still need to validate the trip recording only if the beacon is near the smartphone during the trip.

In this case, the beacon is used in trip validation mode but not in trip detection mode.

If this advanced configuration is not used correctly, it may result in poor trip detection performance.

Please never use this feature without contacting DriveQuant to explain your use case and ensure that this particular mode is mandatory.

How does it work ?

By default, if you have configured a beacon, its detection by the SDK will start a trip analysis.

In very rare cases (e.g. beacon in a vehicle and parked in close proximity to a living area), it might be useful to avoid the SDK to start a trip when a beacon is detected to reduce smartphone battery consumption.

Please note that beacon scans checks are always performed during the trip analysis, even if the configuration is called.

To disable the ability to start a trip analysis when a beacon is detected by DriveKit, you can call the following method:

DriveKitTripAnalysis.shared.allowBeaconTripStart = false

This feature has no effect if the automatic trip detection mode is disabled.

Beacon battery level

DriveKit is able to retrieve the battery level of a beacon and to add this information automatically in trip's metadata (only for the current trip), so that you can know, for instance, if the beacon battery of a user needs to be changed.

For this functionality to work properly, the user must allow access to Bluetooth and you have to configure your project to allow background access to Bluetooth as described below.

Getting the beacon battery level is not essential and if the Bluetooth access permission is not granted or your project not configured as mentioned below, the battery level will not be retrieved but this has no impact on the TripAnalysis auto start mode.

• In your target, in the "Signing & Capabilities" tab, you need to check the "Uses Bluetooth LE accessory" box in "Background Modes":

• Ask the user for Bluetooth access authorization if it is not already granted. To do this, you can call this method:

DKDiagnosisHelper.shared.requestPermission(.bluetooth)

The App Store review team may need to know why the "Uses Bluetooth LE accessory" background mode is needed for your app. To prevent your app from being temporary rejected by Apple during the review process, you should add a note like this in "App Review Information" > "Notes" section of App Store Connect:

• Why is "bluetooth-central" UIBackgroundModes needed?

  If the user has configured a vehicle with "Beacon" autostart mode and a trip analysis has been launched thanks to the detection of this beacon, we scan Bluetooth LE peripherals to retrieve the battery level of the beacon and send it to our backend to eventually warn the user to change his beacon if the battery level is low. Since the trip analysis is usually done in background, we need this UIBackgroundModes.