Using the SDK
A few general notes:
- Customers should avoid using
TripDetectordirectly; to ensure proper functionality, customers should only use the public classTripDetectionManager; TripDetectionManagercan be accidentally initialised multiple times; this got fixed and we print a warning for this now.- Show thread name in log file (“main” or “other”).
- Log current thread on
Common.initializeandTripDetectionManager.enable; initialising the SDK and enabling trip detection outside of main thread may cause issues for trip detection.
The user's phone must be registered through the
Portal before trips recorded on that phone can be uploaded. Depending on the activation method, as selected by the host app, the device may only require one activation.There is currently a limit of one registered phone per user account. If the same user logs in and registers a second phone, trips from the first phone will no longer get uploaded to the server.
Use the DeviceService to activate the device (register the phone) before you start recording trips.
let deviceService = DeviceService(identity: identity)
deviceService.activate(then: { result in
guard let device = result.value else {
print("Something went wrong.")
return
}
// Additional activation for the device.
})
The trip detection manager must be initialized when the application starts, but trip detection and recording does not happen until you explicitly enable it at least once. Use the
enable method to enable trip detection, recording, and trip file upload. Use the disable method to stop, such as when the user logs out.Note that once trip detection is enabled, it remains enabled even if the application restarts or the phone reboots. You only need to explicitly re-enable it if you previously disabled it.
// Enable Trip Detection
tripDetectionManager?.enable(tripStartHandler: { date in
// Do something with the trip start date ...
}, tripEndHandler: { date in
// Do something with the trip end date ...
})
// Disable Trip Detection
tripDetectionManager?.disable()
tripDetectionManager?.enable method has first argument powerMode: PowerMode = .high which is deprecated in SDK 1.16.0 version.
The Bluetooth Trip Detection (BTD thereafter) uses pending connections to Bluetooth LE devices to wake-up the trip detection. The BTD acts as a wake-up trigger, which kick-starts the trip detection. The first implementation is neither required, nor sufficient to start a trip on its own. A trip can still be started without any bluetooth device being detected, and the trip detection is still required to confirm the validity of a trip.
BTD supports both Bluetooth and Bluetooth LE technology. BTD does not support Bluetooth beacon, although these can be used via the Bluetooth LE features (beacon features are not used in the current implementation) BTD makes use of the "Bluetooth classic" as defined in Apple's WWDC 2019. Not all Bluetooth devices support this feature. BTD makes use of the AudioManager to try to infer the presence of regular Bluetooth devices, such as a car infotainment system.
You can check to see if trip detection is enabled.
Manually enable looking for trip.
tripDetectionManager.enableTripDetection()
Manually disable looking for a trip.
tripDetectionManager.disableTripDetection()
Once a Bluetooth device is added to the list of known devices, the Bluetooth trip detection will start detecting automatically.
You can suggest to the framework to start recording a trip.
tripDetectionManager.beginTripRecording()
And also suggest to end recording a trip.
tripDetectionManager.endTripRecording()
You can see how many trips there are to upload by calling:
TripManager.shared.tripsToUplaod()
This number increases when a trip is recorded without a network connection.
To reduce issues related to device support, the SDK provides a list of devices that can be directly used for trip detection.
The list is built using the same technologies used by the SDK for the detection, and insure a higher success rate by not showing devices known to not be compatible with the current implementation.
The list can be accessed via
bluetoothManager.availableBluetoothDevices(callback: { device in
// update your UI based on this
})
BluetoothDevice's can be used in place of CBPeripherals when adding/removing devices.
In order to add a Bluetooth device to the list of known Bluetooth devices you need to call:
TripManager.shared.bluetoothTripDetector()?.availableBluetoothDevices(callback: { device in
print("Discovered a new device \(device)")
})
This does not show any audio devices.
Then one needs to access the trip detection component 'BluetoothTripDetector' (name subject to change for final release). This component includes all the required methods to add or remove Bluetooth devices to and from the list. The list of devices is backed up by the SDK itself in order to provide the simplest implementation. When using the TripUmbrella, a default implement exists and can be used as follows
TripManager.shared.bluetoothTripDetector()?.registerBluetoothDevice(withBluetoothDevice: TripDetection.BluetoothDevice)
In the same fashion, it is possible to remove a Bluetooth device.
TripManager.shared.bluetoothTripDetector()?.unregisterBluetoothDevice((withIdentifier: String)
NOTE: For a full implementation example, check out the Sample App.
At the time of SDK initialization, if the host app wants it can select the upload route for uploading the trip files to the DriveSync server.
SDK has two upload routes host app can choose:
.wifiOnly:Upload data only when connected to a WiFi network..anyNetwork:Upload data when connected to any network.
If the host app doesn't pass the upload route, the SDK will choose
.anyNetwork by default for uploading the trip files.See below example for passing the upload route:
let manager = TripDetectionManager(identity: Identity,
uploadRoute: .wifiOnly,
telemetryEvents: Set,TelemetryEvent>,
externalRecordProviders: [Factory<ExternalRecordProvider>],
features: [Feature])
Also, after initialization the upload route settings can be changed.
See below example:
manager.uploadRoute = .wifiOnly
Last modified 2d ago