> For the complete documentation index, see [llms.txt](https://docs.sentiance.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sentiance.com/implementing-features/insights/crash-insights.md).

# Crash Insights

{% hint style="info" %}
To learn about the Crash Insights feature, check out [this page](/getting-started/features-catalog/crash-insights.md).
{% endhint %}

## 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.

<details>

<summary>iOS</summary>

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

</details>

<details>

<summary>Android</summary>

Open your app <mark style="color:$success;">**`build.gradle`**</mark> file and add the Crash Detection dependency.

{% code title="app/build.gradle" %}

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

{% endcode %}

</details>

<details>

<summary>React Native</summary>

This feature is included after installing the following modules:

* [@sentiance-react-native/core](https://www.npmjs.com/package/@sentiance-react-native/core)
* [@sentiance-react-native/crash-detection](https://www.npmjs.com/package/@sentiance-react-native/crash-detection)

</details>

<details>

<summary>Flutter</summary>

This feature can be added by installing the following packages:

* [sentiance\_core](https://pub.dev/packages/sentiance_core)
* [sentiance\_crash\_detection](https://pub.dev/packages/sentiance_crash_detection)

</details>

## 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:

{% tabs %}
{% tab title="iOS" %}

```swift
Sentiance.shared.isVehicleCrashDetectionSupported
```

{% endtab %}

{% tab title="Android" %}

```kotlin
CrashDetectionApi.getInstance(context).isVehicleCrashDetectionSupported
```

{% endtab %}

{% tab title="React Native" %}

```javascript
import { 
    isVehicleCrashDetectionSupported 
} from '@sentiance-react-native/crash-detection';

const result = isVehicleCrashDetectionSupported();
```

{% endtab %}

{% tab title="Flutter" %}

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

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

{% endtab %}
{% endtabs %}

### Subscribe for Vehicle Crash Events

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.

{% hint style="info" %}
Checkout [Real-time Listeners](/sdk/appendix/real-time-listeners.md) to read more about implementing the SDK's Listeners
{% endhint %}

{% tabs %}
{% tab title="iOS" %}

```swift
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
}
```

{% endtab %}

{% tab title="Android" %}

```java
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();
    }
});
```

{% endtab %}

{% tab title="React Native" %}

<pre class="language-javascript"><code class="lang-javascript">import SentianceCore from "@sentiance-react-native/core";
<strong>import { 
</strong>    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;
});
</code></pre>

{% endtab %}

{% tab title="Flutter" %}
Create a **background.dart** file under your project's **lib** folder with the following code:

{% code title="background.dart" %}

```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;
  });
}
```

{% endcode %}

Add the following code, depending on your target platform.

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

{% code title="AppDelegate.swift" %}

```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)
    }
}
```

{% endcode %}

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

{% code title="MainApplication.kt" %}

```kotlin
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")
    }
}
```

{% endcode %}

{% hint style="info" %}
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](/sdk/appendix/flutter/declaring-3rd-party-plugins.md) for more details.
{% endhint %}
{% endtab %}
{% endtabs %}

### 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:

<table data-header-hidden><thead><tr><th width="199"></th><th></th></tr></thead><tbody><tr><td>Speed at impact</td><td>The estimated speed of the vehicle before the impact, in m/s.</td></tr><tr><td>Magnitude</td><td>The magnitude of the impact, in m/s².</td></tr><tr><td>Delta-V</td><td>The estimated change in velocity at impact, in m/s.</td></tr><tr><td>Confidence</td><td>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.</td></tr><tr><td>Severity</td><td>A categorical severity of the crash (low, medium, high).</td></tr></tbody></table>

### 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.

{% tabs %}
{% tab title="iOS" %}

```swift
Sentiance.shared.invokeDummyVehicleCrash()
```

{% endtab %}

{% tab title="Android" %}

```java
CrashDetectionApi.getInstance(context).invokeDummyVehicleCrash()
```

{% endtab %}

{% tab title="React Native" %}

```javascript
import { 
    invokeDummyVehicleCrash 
} from '@sentiance-react-native/crash-detection';

invokeDummyVehicleCrash();
```

{% endtab %}

{% tab title="Flutter" %}

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

final sentianceCrashDetection = SentianceCrashDetection();
await sentianceCrashDetection.invokeDummyVehicleCrash();
```

{% endtab %}
{% endtabs %}

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.

{% tabs %}
{% tab title="iOS" %}

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

{% endtab %}

{% tab title="Android" %}

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

{% endtab %}

{% tab title="React Native" %}

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

{% endtab %}

{% tab title="Flutter" %}
Inside the `registerCrashDetectionListener` method described in [the subscription section](#subscribe-for-vehicle-crash-events) above, add the following code to register for crash diagnotic updates.

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

{% endtab %}
{% endtabs %}

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