Automatic Collision Notification (ACN)

Zendrive SDK contains a collision detection feature that uses your phone sensors to automatically detect if your car has been in a collision. Zendrive's collision detection is enabled by default when you integrate the SDK, and is active when a trip is in progress.

From Zendrive SDK v9.1.0 onwards, the speed threshold for both high and low-severity collisions (FNOL and ACN) has been reduced from 10 mph to 5 mph, for both iOS and Android. Note that this speed reduction does not affect the current barometer-based collision detection logic.

Collision Confidence Level Assignment

The collisionDetection API generates a single callback when it detects a collision. This callback contains info about the collision and can be used to initiate any emergency responses and automatic contact to loved ones.

Each detected collision is assigned a confidence level: HIGH or LOW. Based on the confidence measure, you may choose to implement custom business logic. The following recommended flow is the simplest course of action.

Zendrive SDK provides both a confidence level and a confidence number. Confidence numbers can be used to set numeric thresholds for different courses of action. An example is given below in our two-tier notification system.

In order to access the iOS collisionDetection API:

• Entitlement and user permissions need to be enabled in applications.

• Customer needs to add a boolean variable to enable the iOS crash detection feature in the pList file in the SDK setup.

Set up Collision Detection in your Application

Integrate the Zendrive SDK in your application (Full instructions: iOS | Android). To process callbacks from the collision:

• iOS: Implement the processAccidentDetected handler in your ZendriveDelegateProtocol.

• Android: implement the onAccident handler in your ZendriveBroadcastReceiver.

iOS

//Swift
import ZendriveSDKSwift

public class ZendriveDelegateManager: NSObject, ZendriveDelegate {

...
    // Register for collision detected callback.
    func processAccidentDetected(_ accidentInfo: AccidentInfo) {
        print("Accident detected by Zendrive SDK.")
    }

...
}

Android

import com.zendrive.sdk.*;
public class MyZendriveBroadcastReceiver extends ZendriveBroadcastReceiver {
    //...

    @Override
    public void onAccident(Context context, AccidentInfo accidentInfo) { ... }

}

Test for Collisions with the Mock Collision API

The mockCollision API provides the raiseMockAccident (iOS) andtriggerMockAccident (Android) functions to trigger a mock collision notification.

After setting up the SDK in collision detection mode, you can test your integration with these methods. This emulates a fake collision and invokes the onAccident handler in the ZendriveBroadcastReceiver.

iOS

@objc public static func raiseMockAccident(_ confidence: AccidentConfidence)

Android

Zendrive.triggerMockAccident(this.getApplicationContext(),
    ZendriveAccidentConfidence.HIGH,
    new ZendriveOperationCallback() {
        @Override
        public void onCompletion(ZendriveOperationResult result) {
            if (result.isSuccess()) {  ...  }
            else { ... }
        }
    }
);

This requires the SDK to be set up and a trip to be in progress.

Crash Detection Feature for iOS

From Zendrive SDK v9.1.0 onwards, the collision notification feature is integrated with the iOS16 collisionDetection API, which facilitates the following actions:

When the Zendrive collision detection is triggered, the iOS 16 collisionDetection API checks for the collision status, and stores it, as follows:

• The status will be NA if there is no iOS alert

• Time, location and other information if a iOS collision alert exists.

The iOS collisionDetection API stores the collision data in the event.data field, which is uploaded to the Zendrive backend. Here's the latest developer documentation for iOS 16 containing integration information for the collision detection feature in iPhone 14.

Opt-in Program for Potential Collision

As an optional feature, Zendrive SDK is capable of delivering a quicker first notification of a potential collision. With this feature, an early notification is generated within seconds of a possible collision event. This callback may be used for a first notification of loss or to initiate emergency services.

The regular collision notification that is generated now serves to confirm or invalidate the quick notification. The following diagram demonstrates a sample flow for this system.

The confidence number labels (HIGH / MEDIUM / LOW) in the flowchart are representations. Each number represents a numeric threshold that can be adjusted in your application without any SDK changes from Zendrive. Sample thresholds: High = 90, Medium = 70, Low = <70. You can create as many thresholds as needed.

Activate the Potential Collision Program

1. Implement the potentialAccident API call in your app.

2. Call setImplementsMultipleAccidentCallbacks with true on your ZendriveConfiguration object.

3. Contact Zendrive at [email protected] to opt-in to the program.

Implement the potentialAccident API call in iOS and Android using the functions below:

iOS

/// [Disabled by default]
    /// This callback is fired on the main thread when a potential accident is detected by the SDK during a drive.
    /// This is a preliminary callback of a potential collision. This collision is confirmed or invalidated by
    ///  `processAccidentDetected(_:)` callback.
    ///
    ///  To enable contact: [email protected](opens in new tab)
    ///
    /// - Parameter accidentInfo: Info about accident.
    ///
    @objc optional func processPotentialAccidentDetected(_ accidentInfo: AccidentInfo)

Android

/**
*
* An early notification of a possible collision. This collision is confirmed or invalidated by
* {@link #onAccident} callback.
*
* @param context       The Context in which the receiver is running.
* @param accidentInfo  Information about the accident.
*/
public void onPotentialAccident(Context context, AccidentInfo accidentInfo) {
}

/**
* Called when Zendrive SDK detects an accident.
*
* @param context      The Context in which the receiver is running.
* @param accidentInfo Information about the accident.
*/
abstract public void onAccident(Context context, AccidentInfo accidentInfo);

Testing Potential Collisions with the mockCollision API

The upgraded mockCollision API provides the ZendriveMockAccidentConfig (iOS) and ZendriveMockAccidentConfiguration (Android) classes to trigger a mock potential collision with the 2-stage notification system.

iOS

/// This class contains parameters required by `ZendriveTest.raiseMockAccidentUsingConfig(using:)` for testing accident flow.
@objc(ZDMockAccidentConfig) public class MockAccidentConfig : NSObject, NSCopying {
    /// This field specifies the confidence for the potential accident callback.
    ///
    /// Default value is `AccidentConfidence.high`.
    ///
    @objc public var potentialAccidentConfidence: AccidentConfidence
    /// This field specifies the confidence for the final accident callback.
    ///
    /// Default value is `AccidentConfidence.high`.
    ///
    @objc public var finalAccidentConfidence: AccidentConfidence
    /// This field specifies the confidence number for the potential accident callback.
    ///
    /// Default value is 70.
    @objc public var potentialAccidentConfidenceNumber: Int32
    /// This field specifies the confidence number for the final accident callback.
    ///
    /// Default value is 70.
    ///
    @objc public var finalAccidentConfidenceNumber: Int32
    /// This field specifies the callback delay (in seconds) between the potential and final accident callback.
    ///
    /// Default value is 20 seconds.
    ///
    @objc public var delayBetweenCallbacks: Int32
    /// This field specifies the vehicle type at the time of potential and final accident callback.
    ///
    /// Default value is `VehicleType.car`.
    ///
    @objc public var vehicleType: VehicleType

    /// This field specifies the collision severity at the time of potential and final accident callback.
    ///
    /// Default value is `CollisionSeverity.high`.
   ///
    @objc public var collisionSeverity: CollisionSeverity

    /// This field specifies the direction of impact at the time of potential accident callback and final accident callback.
    ///
    /// Default value is `DirectionOfImpact.unknown`.
    ///
    @objc public var directionOfImpact: DirectionOfImpact 
    
    /// This method causes the final callback to invalidate the potential callback.
    ///
    /// Invalidating final callbacks have confidence number as 0 and confidence as `AccidentConfidence.invalid`,
    /// signifying that the accident send out via the potential accident callback on further analysis has been reclassified as *not* being an accident.
    ///
    @objc public func invalidateFinalCallback()
}

Android

// configure the accident callback values
        ZendriveMockAccidentConfiguration accidentConfiguration = new ZendriveMockAccidentConfiguration();
        accidentConfiguration.setPotentialCallbackConfidence(ZendriveAccidentConfidence.HIGH);
        accidentConfiguration.setPotentialCallbackConfidenceNumber(65);
        accidentConfiguration.setFinalCallbackConfidence(ZendriveAccidentConfidence.HIGH);
        accidentConfiguration.setFinalCallbackConfidenceNumber(75);
        accidentConfiguration.setDelayBetweenCallbacksSeconds(15);
        accidentConfiguration.setVehicleType(ZendriveVehicleType.CAR);
        accidentConfiguration.setCollisionSeverity(ZendriveCollisionSeverity.HIGH);
        accidentConfiguration.setDirectionOfImpact(ZendriveDirectionOfImpact.FRONT);
        // Before calling this, ensure that sdk has been setup with multiple accident callbacks enabled. See ZendriveConfiguration#setImplementsMultipleAccidentCallbacks(bool)
        Zendrive.triggerMockAccident(applicationContext,
                accidentConfiguration, new ZendriveOperationCallback() {
                    @Override
                    public void onCompletion(ZendriveOperationResult result) {
                        if (result.isSuccess()) {
                            System.out.print("Accident trigger success");
                        } else {
                            System.out.print("Accident trigger failed: " +
                                    result.getErrorMessage());
                        }
                    }
                });
         // potential and final callback triggered on ZendriveBroadcastReceiver with a 15 second gap.

The AccidentInfo Class

The AccidentInfo class in Android and the ZendriveAccidentInfo class in iOS contain key information about the collision. The Vehicle Type accident info object within the SDK collision callback contains a new parameter called vehicle type. It helps to identify the vehicle involved in the collision.

While the default return value is 'car’, if the vehicle involved in the accident is a motorcycle, then the value returned would be ‘motorcycle’. This accident vehicle type update is based on the motorcycle trip classifier output.

The motorcycle classifier has to be enabled in order for the Trip Type variable to display ‘motorcycle’ instead of ‘car’.

iOS

/// Wrapper for meta-information related to an accident detected by the SDK.
@objc(ZDAccidentInfo) public class AccidentInfo : NSObject {
    /// The unique Id of drive during which the accident occured
    @objc public var driveId: String
    /// The location of the accident.
    @objc public var accidentLocation: LocationPoint
    /// The timestamp of the accident in milliseconds since epoch.
    @objc public var timestamp: Int64
    /// The session that was in progress when the accident occured, if a session
    /// was started in the SDK.
    ///
    /// - SeeAlso: `Zendrive.startSession(_:)`
    @objc public var sessionId: String?
    /// The tracking id of the ongoing drive when the accident occured.
    ///
    /// - SeeAlso: `Zendrive.startManualDrive(_:completionHandler:)`
    @objc public var trackingId: String?
    /// The confidence of detected accident.
    @objc public var confidence: AccidentConfidence
    /// Measures an approximate precision of the detected collision. Ranges between 0 to 100.
    ///
    /// Note: A confidence number of 0 indicated that it was *not* an accident.
    /// 0 confidence number can be sent as a part of potential accident callback
    /// to invalidate the previous callback final accident callback for the same accident.
    /// 0 confidence number will never come as a part of potential accident callback.
    ///
    /// Checkout `MockAccidentConfig.invalidateFinalCallback()` to test this scenario during development.
    ///
    @objc public var confidenceNumber: Int32
    /// A unique identifier of this accident.
    @objc public var accidentId: String
    /// Vehicle type detected by SDK at the time of the accident.
    /// Default value is `VehicleType.car`.
    @objc public var vehicleType: VehicleType 
    /// This field specifies the collision severity at the time of potential and final accident callback.
    ///
    /// Default value is `CollisionSeverity.unknown`.
    @objc public var collisionSeverity: CollisionSeverity
    
    /// This field specifies the direction of impact at the time of potential accident callback and final accident callback.
    ///
    /// Default value is `DirectionOfImpact.unknown`.
    ///
    @objc public var directionOfImpact: DirectionOfImpact 

  /// Initializer for `AccidentInfo`.
    /// - Parameters:
    ///   - location: The location of the accident
    ///   - timestamp: The timestamp of the accident in milliseconds since epoch
    ///   - trackingId: The tracking id of the ongoing drive when the accident occured
    ///   - sessionId: The session that was in progress when the accident
    ///                  occurred, if a session was started in the SDK
    ///   - confidence: Confidence measure of the detected accident
    ///   - confidenceNumber: Confidence number of the detected accident
    ///   - accidentId: A unique identifier of this accident
    ///   - driveId: The unique Id of drive during which the accident occured
    ///   - vehicleType: Vehicle type detected by SDK at the time of the accident
    ///   - collisionSeverity: Collision Severity detected by SDK at the time of the accident
    ///   - directionOfImpact: Direction Of Impact detected by SDK at the time of the accident
    /// - Returns: `AccidentInfo` object
    @objc public init(location:LocationPoint, 
                      timestamp: Int64, 
                      trackingId: String?, 
                      sessionId: String?, 
                      confidence: AccidentConfidence, 
                      confidenceNumber: Int32, 
                      accidentId: String, 
                      driveId: String, 
                      vehicleType: VehicleType, 
                      collisionSeverity: CollisionSeverity, 
                      directionOfImpact: DirectionOfImpact)
    
    /// Returns a dictionary that represents the `AccidentInfo` object.
    @objc public func toDictionary() -> [AnyHashable : Any]
    /// Returns a JSON formatted string that represents the `AccidentInfo` object.
    @objc public func toJson() -> String
}

Android

/**
 * Information about an accident detected by the Zendrive SDK. This is provided to the application
 * via the {@link ZendriveBroadcastReceiver#onAccident} callback.
 */
public class AccidentInfo implements Parcelable {
    /**
     * Default constructor.
     */
    public AccidentInfo() {}

    /**
     * An identifier for the drive during which the accident occured. This identifier is unique for a particular
     * driverId with which the SDK is initialized.
     */
    public String driveId;

    /**
     * The timestamp of the accident in milliseconds since epoch.
     */
    public long timestampMillis;

    /**
     * The location of the accident.
     * If the device location near the time of accident cannot be determined, then this
     * value is null.
     */
    @Nullable
    public LocationPoint location;

    /**
     * Tracking id is specified by the enclosing application when it wants to
     * {@link com.zendrive.sdk.Zendrive#startDrive start a drive} manually.
     * This will be null if no tracking id was specified.
     */
    @Nullable
    public String trackingId;

    /**
     * Session id is specified by the enclosing application when it wants to
     * {@link com.zendrive.sdk.Zendrive#startSession record a session}.
     * This will be null if there is no session associated with this drive.
     */
    @Nullable
    public String sessionId;

    /**
     * Confidence measure of the detected accident.
     */
    public ZendriveAccidentConfidence confidence;

    /**
     * A unique identifier of this accident.
     */
    public String accidentId;

    /**
     * This is an experimental feature, disabled by default.
     *
     * For most use cases, {@link #confidence} should be used. Measures an approximate precision of
     * the detected collision. Ranges between 0 to 100, -1 by default. Contact [email protected]
     * to enable the feature.
     */
    public int confidenceNumber;

    /**
     * Vehicle type detected by sdk, at the time of accident.
     * {@link ZendriveVehicleType#CAR} is the default value
     */
    public ZendriveVehicleType vehicleType;

    /**
     * Collision severity of the detected accident.
     * {@link ZendriveCollisionSeverity#UNKNOWN} is the default value
     */
    public ZendriveCollisionSeverity collisionSeverity;
    
    /**
     * Direction of impact of the detected accident.
     * {@link ZendriveDirectionOfImpact#UNKNOWN} is the default value
     */
    public ZendriveDirectionOfImpact directionOfImpact;

The generated collision data has the following structure. This information is useful for business logic, for example, the accidentLocation field is crucial to relay to emergency services.

Sample Accident Info

{
  "driverId" : "sample",
  "accidentLocation" : {"timestamp": 1559065297688, 
                        "latitude": 80.133, 
                        "longitude": 15.12343 },
  "timestamp": 1559065297688,
  "confidence": 0,
  "confidenceNumber": 34,
  "accidentId": "wii8uwju",
  "vehicleType":0,
  "collisionSeverity":0
}