iOS SDK Additional Features

Zendrive SDK provides a number of features that you can use to control how and when trips are detected and where you can implement your business logic.

Collision Detection

Zendrive SDK can detect collision when an accident occurs. The SDK provides a callback to your application when an accident occurs, via ZendriveDelegateProtocol. By default, collision detection is enabled in the SDK and is active when a drive is in progress

See Automatic Collision Notification.

Vehicle Tagging

Zendrive SDK is capable of identifying a vehicle based on a paired Bluetooth ID generated from a Bluetooth stereo, enabling finer detail on whether the user is driving their own vehicle or is a passenger in a different vehicle.

Important Note: Vehicle tagging via Apple Carplay’s wired or wireless connection failed when iOS users tried to connect their phones to their cars. This is because because the UID would differ each time the phone was connected.

SDK v10.0.0 comes with a workaround for this situation. It checks for partial matching of the Bluetooth UID to identify the vehicle and tag the trip accordingly. This should improve the robustness of vehicle tagging but is not guaranteed to work for all Apple Carplay vehicle and phone combinations.

This feature is useful for any customer interested in using the BlueTooth audio vehicle tagging solution.

To Associate or Dissociate A Vehicle

To associate or dissociate a vehicle with the user account, use the following calls:

Swift

/// vehicleId = identifier for vehicle
/// bluetoothId = mac address of vehicle's bluetooth device
let vehicleInfo = VehicleInfo(vehicleId: "vehicleId",
                              bluetoothId: "14:0F:C6:62:F8:9E")

/// After successful association of vehicle information, whenever ZendriveSDK will detect
/// a connection to this bluetooth device while the user is driving, it will tag the trip
/// with vehicleId of this vehicle. throws error if association is not successful.
try ZendriveVehicleTagging.associateVehicle(vehicleInfo)

/// returns the list of vehicles associated to SDK.
/// Associating more than two vehicles is not allowed.
let associatedVehicles = ZendriveVehicleTagging.getAssociatedVehicles()

/// Takes vehicleId of vehicle(which is to be dissociated) as an input
/// After successful dissociation of the vehicle, ZendriveSDK will stop
/// tagging the trips for this vehicle, throws error if dissociation fails.
try ZendriveVehicleTagging.dissociateVehicle(vehicleInfo.vehicleId)

Objective-C

// vehicleId = identifier for vehicle
// bluetoothId = mac address of vehicle's bluetooth device
ZendriveVehicleInfo *vehicleInfo = [[ZendriveVehicleInfo alloc]
                                    initWithVehicleId:@"vehicleId"
                                    bluetoothId: @"14:0F:C6:62:F8:9E"];
NSError *associateError;

// After successful association of vehicle information, whenever ZendriveSDK will detect
// a connection to this bluetooth device while the user is driving, it will tag the trip
// with vehicleId of this vehicle
// error thrown by this will be populated in associateError.
BOOL associateSuccess = [ZendriveVehicleTagging associateVehicle:vehicleInfo error:&associateError];

// returns the list of vehicles associated to SDK.
// Associating more than two vehicles is not allowed.
NSArray<ZendriveVehicleInfo *> *associatedVehicles = [ZendriveVehicleTagging
                                                     getAssociatedVehicles];
NSError *dissociateError;

// Takes vehicleId of vehicle(which is to be dissociated) as an input
// After successful dissociation of the vehicle, ZendriveSDK will stop
// tagging the trips for this vehicle.
// error thrown by this will be populated in dissociateError.
BOOL dissociateSuccess = [ZendriveVehicleTagging dissociateVehicle:vehicleInfo.vehicleId error:&dissociateError];

Vehicle tagging aids vehicle-restricted insurance in case the user drives multiple vehicles. This feature is also used for tying usage metrics to a vehicle rather than a user. This is useful in case multiple family members drive the same vehicle, or in cases where a fleet owner needs metrics on specific vehicles.

The DriveInfo class now has a tags array. The getAssociatedVehicleForDrive function fetches the vehicleId tag from the tags array.

Swift

@objc(ZDDriveInfo) public class DriveInfo : NSObject {
    ...
    /// tags array for the drive, it will only be populated in AnalyzedDriveInfo.
    @objc public var tags: [TagInfo]
    ...
}
/// Use ZendriveVehicleTagging.getAssociatedVehicleIdForDrive(analyzedDriveInfo)
/// to get the vehicleId from the AnalyzedDriveInfo object.
func processAnalysis(ofDrive analyzedDriveInfo: AnalyzedDriveInfo) {
    /// returns vehicleId if tags array contains the vehicleId tag
    /// otherwise returns nil
    let vehicleId =
        ZendriveVehicleTagging.getAssociatedVehicleForDrive(analyzedDriveInfo)
}

Objective-C

@interface ZendriveDriveInfo : NSObject
...
/// tags array for the drive, it will only be populated in ZendriveAnalyzedDriveInfo
@property (nonatomic, strong, nonnull) NSArray<ZendriveTagInfo *> *tags;
...
@end
/// Use [ZendriveVehicleTagging getAssociatedVehicleForDrive:analyzedDriveInfo]
/// to get the vehicleId from the ZendriveAnalyzedDriveInfo object.
- (void)processAnalysisOfDrive:(nonnull ZendriveAnalyzedDriveInfo *)analyzedDriveInfo {
    // returns vehicleId if tags array contains the vehicleId tag
    // otherwise returns nil
    NSString *vehicleId = [ZendriveVehicleTagging
                           getAssociatedVehicleForDrive:analyzedDriveInfo];
}

Active Bluetooth Connection

On iOS, you can tag any BluetoothA2DP or Bluetooth hands-free profile as long as the connection is active for some time during the trip. The connection is considered active if the audio is playing through that device, not a different connected device, for example, the user's bluetooth earbuds.

If the user does not have multiple connected audio devices, then the connected stereo is the active connection.

Cases

Incorrect Case 1: The user is connected to their car’s bluetooth but the user's Airpods are the active connection throughout the drive. In this scenario, the stereo is not active even once during the trip, and the SDK can only discover connection to the Airpods. Hence, the trip will not be tagged.

Incorrect Case 2: The user is connected to their car’s bluetooth, but is also using headphones throughout the drive. In this case, the audio route never goes to the stereo and the trip will not be tagged.

Incorrect Case 3: The user is connected to their car's bluetooth, but audio is being routed via a USB connection between the phone and the car’s speaker throughout the drive. The trip will not be tagged.

Correct Case 1: The user is not connected to multiple devices, and their stereo is on. The audio route is set to the car stereo, and the SDK will be able to detect the stereo and tag the vehicle.

Correct Case 2: The user is using Airpods for part of the drive, but switches to car stereo audio. In this case, the audio route switches to the car stereo, and the SDK can detect it and tag the trip.

Manual Trip Tagging

Zendrive SDK works in the background and automatically detects trips and tracks driving behaviour. However, some applications, such as taxi-metering apps, already have knowledge of point-to-point trips made by the driver using the application.

If your application has this knowledge, it can explicitly provide it to Zendrive SDK.

Swift

Zendrive.startManualDrive("tracking-id") { (success: Bool, error: Error?) in
    print("Manual Start Drive Call Completed !");
}

Zendrive.stopManualDrive { (success, error) in
    print("Manual Stop Drive Call Completed !");            
}

Objective-C

[Zendrive startManualDrive:@"tracking-id"
         completionHandler:^(BOOL success, NSError * _Nullable error) {
    NSLog(@"Manual Start Drive Call Completed !");
}];
    // Non-nil and non-empty tracking id
[Zendrive stopManualDrive:^(BOOL success, NSError * _Nullable error) {
    NSLog(@"Manual Stop Drive Call Completed !");
}];

Your application can then use the tracking-id argument to find Zendrive trips with this ID in the Zendrive Server APIs. See the SDK Reference for more information.

Driving Sessions

Some applications want to track multiple point-to-point trips together as a single entity. For example, a car rental application may want to track all trips made by a user between a rental car pickup and drop-off as a single entity. You can do this using sessions in Zendrive SDK. Use the following calls to use sessions.

Swift

Zendrive.startSession("session-id") // Non-nil and non-empty session id

...

Zendrive.stopSession()

Objective-C

[Zendrive startSession:@"session-id"]; // Non-nil and non-empty session id

...

[Zendrive stopSession];

The Zendrive SDK tags all trips within a session with a single session-id. You can then use the session-id argument to lookup Zendrive trips belonging to this session using the Zendrive Analytics API. See the SDK Reference for more.

Controlling Automatic Drive Detection

Zendrive SDK works in the background and automatically detects trips and tracks driving behaviour. If needed, an application can change this behaviour. For example, a ride-sharing application may want to automatically track all trips made by a driver only on duty.

This can be done by setting the appropriate ZendriveDriveDetectionMode. The application can specify the required behavior during setup of Zendrive SDK.

Swift

...
// DriveDetectionMode.autoOFF disables automatic drive detection in the SDK.
let configuration: Configuration = Configuration()
configuration.driveDetectionMode = .autoOFF
...

Zendrive.setup(with: configuration, delegate: zdDelegate) { (success: Bool, error: Error?) in
    if success {} 
    else {}
}

Objective-C

...
// ZendriveDriveDetectionModeAutoOFF disables automatic drive detection in the SDK.
ZendriveConfiguration *configuration = [[ZendriveConfiguration alloc] init];
configuration.driveDetectionMode = ZendriveDriveDetectionModeAutoOFF;
...

[Zendrive setupWithConfiguration:configuration
                        delegate:zdDelegate
               completionHandler:^(BOOL success, NSError *error) {
    if(success) { ... }
    else { ... }
}];

The application can also temporarily toggle Zendrive's auto drive-detection. This can be done by setting the ZendriveDriveDetectionMode.

Swift

// This will turn OFF Zendrive SDK's auto drive-detection.
Zendrive.setDriveDetectionMode(.autoOFF) { (success: Bool, error: Error?) in
    if isSuccess {
        print("Drive detection mode changed to AutoOFF");
    } else {
        print("setDriveDetectionMode:(AutoOFF) call failed");
    }
}

// This will turn ON Zendrive SDK's auto drive-detection.
Zendrive.setDriveDetectionMode(.autoON) { (success: Bool, error: Error?) in
    if isSuccess {
        print("Drive detection mode changed to AutoOFF");
    } else {
        print("setDriveDetectionMode:(AutoON) call failed");
    }
}

Objective-C

// This will turn OFF Zendrive SDK's auto drive-detection.
[Zendrive setDriveDetectionMode:ZendriveDriveDetectionModeAutoOFF
              completionHandler:^(BOOL isSuccess, NSError *_Nullable error) {
                                if (isSuccess) {
                                    NSLog(@"Drive detection mode changed to AutoOFF");
                                } else {
                                    NSLog(@"setDriveDetectionMode:(AutoOFF) call failed, with code:%li, and description:%@",error.code,error.localizedDescription);
                                }
                            }];
...
// This will turn ON Zendrive SDK's auto drive-detection.
[Zendrive setDriveDetectionMode:ZendriveDriveDetectionModeAutoON
              completionHandler:^(BOOL isSuccess, NSError *_Nullable error) {
                                if (isSuccess) {
                                    NSLog(@"Drive detection mode changed to AutoON");
                                } else {
                                       NSLog(@"setDriveDetectionMode:(AutoON) call failed, with code:%li, and description:%@",error.code,error.localizedDescription);
                                  }
                            }];