Crash Insights

To learn about the Crash Insights feature, check out this page.

Prerequisites

The Crash Insights feature relies on additional library dependencies alongside the core SDK dependency. To start using this feature, you must first add these dependencies to you project.

iOS

This feature is included in the main SDK framework. No additional dependencies are needed.

Android

Open your app build.gradle file and add the Crash Detection dependency.

app/build.gradle

dependencies {
    implementation(platform('com.sentiance:sdk-bom:<sentiance-version>'))
    implementation('com.sentiance:sdk-crash-detection')
}

React Native

This feature is included after installing the following modules:

Flutter

This feature can be added by installing the following packages:

Utilize the Crash Detection APIs

In this section, you’ll find examples showing how to check whether vehicle crash detection is supported on a device, how to subscribe to crash event notifications, and additional details about the contents of a crash event and how to test your integration.

Check if Vehicle Crash Detection Is Supported

There are several reasons why vehicle crash detection may not be supported on the device. The two most common of these are:

the feature is not enabled for your app;
the device lacks the necessary sensors (e.g. accelerometer).

You can check to see whether vehicle crash detection is support on the device, as follows:

Sentiance.shared.isVehicleCrashDetectionSupported

import 'package:sentiance_crash_detection/sentiance_crash_detection.dart';

final sentianceCrashDetection = SentianceCrashDetection();
bool result = await sentianceCrashDetection.isVehicleCrashDetectionSupported();

In order to be notified of vehicle crash events, you can specify the listener that the SDK will invoke when it detects a vehicle crash.

Checkout Real-time Listeners to read more about implementing the SDK's Listeners

Sentiance.shared.setVehicleCrashHandler { crashEvent in
    let date = crashEvent.date
    let confidence = crashEvent.confidence
    let deltaV = crashEvent.deltaV
    let magnitude = crashEvent.magnitude
    let speedAtImpact = crashEvent.speedAtImpact
    let location = crashEvent.location
    let severity = crashEvent.severity
}

CrashDetectionApi.getInstance(context).setVehicleCrashListener(new VehicleCrashListener() {
    @Override
    public void onVehicleCrash(VehicleCrashEvent crashEvent) {
        long epochTimeMs = crashEvent.getTime();
        Location location = crashEvent.getLocation();
        Float speedAtImpact = crashEvent.getSpeedAtImpact();
        Float magnitude = crashEvent.getMagnitude();
        Float deltaV = crashEvent.getDeltaV();
        Integer confidence = crashEvent.getConfidence();
        VehicleCrashSeverity severity = crashEvent.getSeverity();
    }
});

import SentianceCore from "@sentiance-react-native/core";
import { 
    addVehicleCrashEventListener 
} from '@sentiance-react-native/crash-detection';

await SentianceCore.ensureInitialized();

addVehicleCrashEventListener(crashEvent => {
    const time = crashEvent.time;
    const location = crashEvent.location;
    const magnitude = crashEvent.magnitude;
    const speedAtImpact = crashEvent.speedAtImpact;
    const deltaV = crashEvent.deltaV;
    const confidence = crashEvent.confidence;
    const severity = crashEvent.severity;
});

Create a background.dart file under your project's lib folder with the following code:

background.dart

import 'package:sentiance_crash_detection/sentiance_crash_detection.dart';
import 'package:sentiance_core/sentiance_core.dart';

@pragma('vm:entry-point')
void registerCrashDetectionListener() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SentianceCore.ensureInitialized();

  // Subscribe for vehicle crash events
  SentianceCrashDetection.registerCrashListener((crashEvent) {
    // Handle the vehicle crash event

    final epochTimeMs = crashEvent.time;
    final location = crashEvent.location;
    final speedAtImpact = crashEvent.speedAtImpact;
    final magnitude = crashEvent.magnitude;
    final deltaV = crashEvent.deltaV;
    final confidence = crashEvent.confidence;
    final severit = crashEvent.severity;
  });
}

Add the following code, depending on your target platform.

For iOS, add the following to your app delegate class:

AppDelegate.swift

import Flutter
import sentiance_crash_detection

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
    
        // Other code
        
        // Make sure the SDK is initialized before calling this
        SentianceCrashDetectionPlugin.initializeListener(
            withEntryPoint: "registerCrashDetectionListener",
            libraryURI: "package:your_app_package_name/background.dart"
        )
        
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

For Android, add this code to your custom application class:

MainApplication.kt

import android.app.Application
import com.sentiance.crash_detection_plugin.CrashDetectionPlugin

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Other code

        val dartLibrary = "package:your_app_package_name/background.dart"
        // Make sure the SDK is initialized before calling this
        CrashDetectionPlugin.initializeListener(this, dartLibrary, "registerCrashDetectionListener")
    }
}

If you're calling other Crash Detection plugin APIs or other 3rd party plugin APIs inside your registerCrashDetectionListener Dart function, then you need to register these plugins with the Sentiance SDK. See this for more details.

Crash Event Details

A crash event contains the time and location of the detected crash, in addition to a number of metrics to estimate the severity of the crash:

Speed at impact

The estimated speed of the vehicle before the impact, in m/s.

Magnitude

The magnitude of the impact, in m/s².

Delta-V

The estimated change in velocity at impact, in m/s.

Confidence

The level of confidence that the accelerometer signal reflects a true crash pattern (range 0 - 100). It is recommended to filter out events below the confidence of 50.

Severity

A categorical severity of the crash (low, medium, high).

Test Your Integration

The final step is checking your integration, to make sure that your vehicle crash listener is properly set up to handle crash events. Add the following method call in your app to trigger a dummy crash event.

Sentiance.shared.invokeDummyVehicleCrash()

This would invoke your listener, passing it a dummy crash event. You can test how your app handles the event at runtime.

Crash Detection Diagnostic Information

It’s also possible to subscribe to additional diagnostic data produced by the SDK to better understand the state and decision-making of the crash detection and to facilitate testing.

Sentiance.shared.setVehicleCrashDiagnosticHandler { diagnostic in
    let state = diagnostic.crashDetectionState
    let description = diagnostic.crashDetectionStateDescription
}

CrashDetectionApi.getInstance(context).setVehicleCrashDiagnosticListener { diagnostic ->
    val state = diagnostic.crashDetectionState
    val description = diagnostic.crashDetectionStateDescription
}

await SentianceCrashDetection.addVehicleCrashDiagnosticListener(diagnostic => {
    const state = diagnostic.crashDetectionState;
    const description = diagnostic.crashDetectionStateDescription;
}

Inside the registerCrashDetectionListener method described in the subscription section above, add the following code to register for crash diagnotic updates.

 SentianceCrashDetection.registerCrashDiagnosticListener((diagnostic) {
    final state = diagnostic.crashDetectionState;
    final description = diagnostic.crashDetectionStateDescription;
 });

The result will reflect one of the following states:

Crash candidate detected
Crash candidate discarded - impact is too weak
Crash candidate discarded - transport mode is not a vehicle
Crash candidate discarded - pre-impact signal contains too much noise
Crash candidate discarded - speed before impact is too low
Crash candidate discarded - post-impact signal contains too much noise
Crash candidate discarded - speed after impact is too high

PreviousLifestyle Insights NextSmart Geofences

Last updated 11 days ago