Driving Insights

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

Prerequisites

The Driving 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 driving insights dependency.

app/build.gradle

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

React Native

This feature is included after installing the following modules:

Flutter

This feature can be added by installing the following packages:

Utilize the Driving Insights APIs

In this section, you can find examples of how to query the Sentiance SDK for driving insights, safe driving scores, detailed driving events. You will also find how to register to be notified of driving insights, once it becomes available.

Query for Driving Insights

Driving Insights become available a few minutes after a transport ends. Once the user stops driving, the SDK takes a few minutes to make sure that the drive is over, and then proceeds to prepare the insights.

To be notified of when the insights are ready, you can subscribe for Driving Insights updates.

To retrieve driving insights, use the getDrivingInsights method.

let sentiance = Sentiance.shared
if let drivingInsights = sentiance.getDrivingInsights(forTransportId: transportId) {
    let event = drivingInsights.transportEvent
    let safetyScores = drivingInsights.safetyScores
    
    print("Focus score: \(safetyScores.focusScore ?? -1)")
    print("Legal score: \(safetyScores.legalScore ?? -1)")
    print("Smooth score: \(safetyScores.smoothScore ?? -1)")
    print("Call-while-moving score: \(safetyScores.callWhileMovingScore ?? -1)")
    print("Overall score: \(safetyScores.overallScore ?? -1)")

    print("Event ID: \(event.eventId)")
    print("Started on: \(event.startDate)")
    print("Ended on: \(String(describing: event.endDate))")
    print("Mode: \(event.transportMode)")

    if let distanceInMeters = event.distanceInMeters {
        print("Distance: \(distanceInMeters)")
    }

    print("Waypoints: \(event.waypoints)")
}

val drivingInsightsApi = DrivingInsightsApi.getInstance(context)
val drivingInsights = drivingInsightsApi.getDrivingInsights(transportId)
if (drivingInsights != null) {
    val event = drivingInsights.transportEvent
    val safetyScores = drivingInsights.safetyScores

    print("Focus score: ${safetyScores.focusScore}")
    print("Legal score: ${safetyScores.legalScore}")
    print("Smooth score: ${safetyScores.smoothScore}")
    print("Call-while-moving score: ${safetyScores.callWhileMovingScore}")
    print("Overall score: ${safetyScores.overallScore}")

    print("Event ID: ${event.id}")
    print("Started on: ${event.startTime}")
    print("Ended on: ${event.endTime}")
    print("Mode: ${event.transportMode}")

    if (event.distanceInMeters != null) {
        print("Distance: ${event.distanceInMeters}")
    }

    print("Waypoints: ${event.waypoints}")
}

import SentianceDrivingInsights from "@sentiance-react-native/driving-insights";

const drivingInsights = await SentianceDrivingInsights.getDrivingInsights(transportId);

if (drivingInsights !== null) {
    const event = drivingInsights.transportEvent; 
    const safetyScores = drivingInsights.safetyScores;
    
    if (safetyScores.focusScore) {
        console.log(`Focus score: ${safetyScores.focusScore}`);
    }
    if (safetyScores.legalScore) {
        console.log(`Legal score: ${safetyScores.legalScore}`);
    }
    if (safetyScores.smoothScore) {
        console.log(`Smooth score: ${safetyScores.smoothScore}`);
    }
    if (safetyScores.callWhileMovingScore) {
        console.log(`Call-while-moving score: ${safetyScores.callWhileMovingScore}`);
    }
    if (safetyScores.overallScore) {
        console.log(`Overall score: ${safetyScores.overallScore}`);
    }
    
    console.log(`Event ID: ${event.id}`);
    console.log(`Started on: ${event.startTime}`);
    console.log(`Ended on: ${event.endTime}`);
    console.log(`Mode: ${transport.transportMode}`);
    
    if (event.distance) {
        console.log(`Distance: ${event.distance}`);
    }
    console.log(`Waypoints: ${JSON.stringify(event.waypoints)}`);
}

import 'package:sentiance_driving_insights/sentiance_driving_insights.dart';

final sentianceDrivingInsights = SentianceDrivingInsights();

void getDrivingInsightsForTransport() async {
  String transportId = "your_transport_id";
  final drivingInsights = await sentianceDrivingInsights.getDrivingInsights(transportId);
  if (drivingInsights != null) {
    final transportEvent = drivingInsights.transportEvent;
    final safetyScores = drivingInsights.safetyScores;
    
    print('Focus score: ${safetyScores.focusScore}');
    print('Legal score: ${safetyScores.legalScore}');
    print('Smooth score: ${safetyScores.smoothScore}');
    print('Call-while-moving score: ${safetyScores.callWhileMovingScore}');
    print('Overall score: ${safetyScores.overallScore}');

    print('Event ID: ${transportEvent.id}');
    print('Started on: ${transportEvent.startTimeMs}');
    print('Ended on: ${transportEvent.endTimeMs}');
    print('Last updated on: ${transportEvent.lastUpdateTimeMs}');
    print('Mode: ${transportEvent.transportMode}');
    print('Duration in seconds: ${transportEvent.durationInSeconds}');
    print('Distance: ${transportEvent.distance}');
    print('Waypoints: [${transportEvent.waypoints.map((wp) => wp.toString()).join(", ")}]');
  }
}

Query For Driving Events

The Sentiance SDK offers more granular driving insights. You can retrieve detailed events, such as speeding and harsh driving, as shown below.

// Harsh driving events, used for computing the smooth driving score
Sentiance.shared.getHarshDrivingEvents(forTransportId: transportId).forEach { harshDrivingEvent in
    print("Start date: \(harshDrivingEvent.startDate)")
    print("End date: \(harshDrivingEvent.endDate)")
    print("Magnitude: \(harshDrivingEvent.magnitude)")
}

// Phone usage events, used for computing the focused driving score
Sentiance.shared.getPhoneUsageEvents(forTransportId: transportId).forEach { phoneUsageEvent in
    print("Start date: \(phoneUsageEvent.startDate)")
    print("End date: \(phoneUsageEvent.endDate)")
}

// Call-while-moving events, used for computing the call-while-moving score
Sentiance.shared.getCallsWhileMovingEvents(forTransportId: transportId).forEach { callWhileMovingEvent in
    print("Start date: \(callWhileMovingEvent.startDate)")
    print("End date: \(callWhileMovingEvent.endDate)")
    if let minSpeed = callWhileMovingEvent.minTraveledSpeedInMps?.floatValue {
        print("Min traveled speed: \(minSpeed)")
    }
    if let maxSpeed = callWhileMovingEvent.maxTraveledSpeedInMps?.floatValue {
        print("Max traveled speed: \(maxSpeed)")
    }
}

// Speeding events, used for computing the legal driving score
Sentiance.shared.getSpeedingEvents(forTransportId: transportId).forEach { speedingEvent in
    print("Start Date: \(speedingEvent.startDate)")
    print("End Date: \(speedingEvent.endDate)")
    print("Waypoints: \(speedingEvent.waypoints)")
}

// Harsh driving events, used for computing the smooth driving score
DrivingInsightsApi.getInstance(context).getHarshDrivingEvents(transportId)
  .forEach { harshDrivingEvent -> 
    print("Start time: ${harshDrivingEvent.startTime}")
    print("End time: ${harshDrivingEvent.endTime}")
    print("Magnitude: ${harshDrivingEvent.magnitude}")
}

// Phone usage events, used for computing the focused driving score
DrivingInsightsApi.getInstance(context).getPhoneUsageEvents(transportId)
  .forEach { phoneUsageEvent ->
    print("Start time: ${phoneUsageEvent.startTime}")
    print("End time: ${phoneUsageEvent.endTime}")
}

// Call-while-moving events, used for computing the call-while-moving score
DrivingInsightsApi.getInstance(context).getCallWhileMovingEvents(transportId)
  .forEach { callWhileMovingEvent ->
    print("Start time: ${callWhileMovingEvent.startTime}")
    print("End time: ${callWhileMovingEvent.endTime}")
    print("Min traveled speed: ${callWhileMovingEvent.minTraveledSpeedInMps}")        
    print("Max traveled speed: ${callWhileMovingEvent.maxTraveledSpeedInMps}")        
}

// Speeding events, used for computing the legal driving score
DrivingInsightsApi.getInstance(context).getSpeedingEvents(transportId)
  .forEach { speedingEvent ->
    print("Start time: ${speedingEvent.startTime}")
    print("End time: ${speedingEvent.endTime}")
    print("Waypoints: ${speedingEvent.waypoints}")
}

import SentianceDrivingInsights from "@sentiance-react-native/driving-insights";

// Harsh driving events, used for computing the smooth driving score
const harshDrivingEvents = await SentianceDrivingInsights.getHarshDrivingEvents(transportId);
for (const event of harshDrivingEvents) {
    console.log(`Start time: ${event.startTime}`);
    console.log(`End time: ${event.endTime}`);
    console.log(`Magnitude: ${event.magnitude}`);
}

// Phone usage events, used for computing the focused driving score
const phoneUsageEvents = await SentianceDrivingInsights.getPhoneUsageEvents(transportId);
for (const event of phoneUsageEvents) {
    console.log(`Start time: ${event.startTime}`);
    console.log(`End time: ${event.endTime}`);
}

// Call-while-moving events, used for computing the call-while-moving score
const callWhileMovingEvents = await SentianceDrivingInsights.getCallWhileMovingEvents(transportId);
for (const event of callWhileMovingEvents) {
    console.log(`Start time: ${event.startTime}`);
    console.log(`End time: ${event.endTime}`);
    console.log(`Min traveled speed: ${event.minTravelledSpeedInMps}`);        
    console.log(`Max traveled speed: ${event.maxTravelledSpeedInMps}`);
}

// Speeding events, used for computing the legal driving score
const speedingEvents = await SentianceDrivingInsights.getSpeedingEvents(transportId);
for (const event of speedingEvents) {
    console.log(`Start time: ${event.startTime}`);
    console.log(`End time: ${event.endTime}`);
    console.log(`Waypoints: ${JSON.stringify(event.waypoints)}`);
}

import 'package:sentiance_driving_insights/sentiance_driving_insights.dart';

final sentianceDrivingInsights = SentianceDrivingInsights();

void fetchDrivingEvents(String transportId) async {
  // Harsh driving events, used for computing the smooth driving score
  final harshDrivingEvents = await sentianceDrivingInsights.getHarshDrivingEvents(transportId);
  for (final event in harshDrivingEvents) {
    print('Start time: ${event.startTimeMs}');
    print('End time: ${event.endTimeMs}');
    print('Magnitude: ${event.magnitude}');
  }

  // Phone usage events, used for computing the focused driving score
  final phoneUsageEvents = await sentianceDrivingInsights.getPhoneUsageEvents(transportId);
  for (final event in phoneUsageEvents) {
    print('Start time: ${event.startTimeMs}');
    print('End time: ${event.endTimeMs}');
  }

  // Call-while-moving events, used for computing the call-while-moving score
  final callWhileMovingEvents = await sentianceDrivingInsights.getCallWhileMovingEvents(transportId);
  for (final event in callWhileMovingEvents) {
    print('Start time: ${event.startTimeMs}');
    print('End time: ${event.endTimeMs}');
    print('Min traveled speed: ${event.minTraveledSpeedInMps}');
    print('Max traveled speed: ${event.maxTraveledSpeedInMps}');
  }

  // Speeding events, used for computing the legal driving score
  final speedingEvents = await sentianceDrivingInsights.getSpeedingEvents(transportId);
  for (final event in speedingEvents) {
    print('Start time: ${event.startTimeMs}');
    print('End time: ${event.endTimeMs}');
    print('Waypoints: ${event.waypoints}');
  }
}

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

class MyDelegate: DrivingInsightsReadyDelegate {
    func onDrivingInsightsReady(insights: SENTSDK.DrivingInsights) {
        let transportEvent = insights.transportEvent
        let safetyScores = insights.safetyScores
    }
}
        
Sentiance.shared.drivingInsightsReadyDelegate = MyDelegate()

val drivingInsightsApi = DrivingInsightsApi.getInstance(context)

drivingInsightsApi.setDrivingInsightsReadyListener { insights ->
    val transportEvent = insights.transportEvent
    val safetyScores = insights.safetyScores
}

To get driving insights updates even when your app is in the background, place the following code inside your app's entrypoint index.js file. If you're only interested in these updates when your app is foregrounded, place this code inside the appropriate UI code instead.

import SentianceDrivingInsights from "@sentiance-react-native/driving-insights";
import SentianceCore from "@sentiance-react-native/core";

await SentianceCore.ensureInitialized(); // Ensure SDK is initialized first

// If you're subscribing to updates only in the foreground, make sure
// to call subscription.remove() inside your component's componentWillUnmount() function
const subscription = await SentianceDrivingInsights.addDrivingInsightsReadyListener(drivingInsights => {
    // Handle the insights here (see the Query for Driving Insights
    // example above).
});

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

background.dart

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

@pragma('vm:entry-point')
void registerDrivingInsightsListener() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SentianceCore.ensureInitialized();
  
  SentianceDrivingInsights.registerDrivingInsightsListener((drivingInsights) {
    // Handle the insights here (see the Query for Driving Insights
    // example above).
  });
}

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_driving_insights

@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
        SentianceDrivingInsightsPlugin.initializeListener(
            withEntryPoint: "registerDrivingInsightsListener",
            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.driving_insights_plugin.DrivingInsightsPlugin

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
        DrivingInsightsPlugin.initializeListener(this, dartLibrary, "registerDrivingInsightsListener")
    }
}

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

PreviousInsights NextMobility Insights

Last updated 11 days ago

Prerequisites

Utilize the Driving Insights APIs

Query for Driving Insights

Query For Driving Events

Subscribe for Driving Insights Updates