Understanding Features & Methods of Kruzr SDK
Before you start integrating Kruzr SDK into your applications, it is important to understand the core SDK features, how those features are defined and work as part of Kruzr platform and the corresponding methods available in iOS and Android.
The following subsections within this topic will take you through 4 key features currently offered with our SDKs. They are -
Driving State and Trip Definitions
Driving Data Collection
Trip Scoring Calculation
Trip Summary Generation
Kruzr SDKs offer best in class algorithms for Driving State identification models and Trip State definitions. Assuming all necessary permissions have been received from the user, Kruzr SDK will automatically identify driving activities for your users and the current trip state for an ongoing trip.
There are also manual override options available in the SDK which will help you to provide manual Trip Start/End options to your users.
Before diving deeper into these methods and states available for driving and trip states, it is important to understand how Trips and Driving States are defined within our platform.
What are Driving States on Kruzr SDK?
As mentioned above, Kruzr SDK offers in-built driving detection logics for both iOS and Android. Over the past 3 years, we have developed a sophisticated multi-level driving detection logic which utilizes sensors data, phone OS motion state and the GPS. Using this we are able to differentiate between driving vs non-driving motion states using the driver's phone.
Note that there will be cases where "False Positives" are identified due to limitations of sensor noise and/or App Side Processing capabilities. However, we have built another level of driving detection checks in our latest trip processing APIs which are able to further differentiate between motorized vs non-motorized trips (e.g. a cycle trip vs a car trip). The second level check also ensures that all the trips your data science teams receive from us are, almost exclusively, actual car trips.
What is a Trip on Kruzr SDK?
We can define a trip in four ways, depending on whether Driving State was started or ended automatically or manually -
For Automatic Start AND Automatic End - A trip is defined as the time period between which "Motion Engine" logic has identified that the user has started "Driving" and till the point user has reached "Final Stop" according to our "Motion Engine".
For Automatic Start AND Manual End - In this case, a trip is defined as the time period between which "Motion Engine" logic has identified that the user has started "Driving" and till the point app has provided us with "Manual Trip End".
For Manual Start AND Manual Trip End - In this case, a trip is defined as the time period between which user/app has provided us with "Manual Trip Start" and until "Manual Trip End".
For Manual Start AND Automatic Trip End - In this case, a trip is defined as the time period between which user/app has provided us with "Manual Trip Start" and our "Motion Engine" has returned a "Final Stop" post the trip start.
Within your app, you can also cover all of the above cases based on your design preferences and user needs using our SDK.
How Driving States and Trip State work together to create Trip Lifecycle?
Another helpful item to understand is the "Trip Lifecycle" from the following chart. A trip typically has multiple states from Driving Detection until a Final Stop/Trip End is reached. A detailed schematic diagram of this flow is shown below. Please note the diagram below is the complete universe of Trip and Driving States offered within Android. There may be differences in between both, Trip and Driving states available within Android vs iOS due to differences in flexibility of platform and relevant functionalities for which SDK uses Driving and Trip States on respective devices.
Data & Scoring related background SDK activities during a Trip Lifecycle
In order to generate usage and contextual scoring for your users, Kruzr SDK does the following activities automatically for your app in background during a typical Trip Lifecycle -
At Trip Initiation:
Sensor data file creation
Event data file creation
During On-Going Trip:
Sensor file updates from driving data at high frequency
Event file updates from driving data at 1 event per second
Sync location with Kruzr Cloud APIs to capture and store real time traffic and weather context at vehicle's location every 3 seconds of an on-going trip
At Trip End:
Once a trip has reached "Trip End" in the life cycle, the SDK waits for user's device to connect to a Wifi by default.
When a Wifi connection for the device has been confirmed, the two trip files required for further scoring, i.e. the Sensor and Events File are automatically uploaded to our Cloud for further scoring
Once scoring is completed for a particular user, it is available for consumption either through your app or our dashboards
Note: You can choose whether you want to sync data over wifi only, or both wifi and cellular data with Sync Preferences
Methods and Feature Mapping within SDK
We have discussed all necessary details regarding Kruzr SDK's Trip, Driving State and Scoring methodologies. We can now deep dive into the methods available to your app and map those methods to the understanding of Trip, Driving states we just developed. The detailed technical implementation are discussed in respective sections "Building an Android App with Kruzr SDK" and "Building an iOS App with Kruzr SDK" sections. However, we recommend that you continue reading this article to help you map and understand implications of methods we discuss in those sections and how they relate to your app's lifecycles. Parameters for each method has NOT been mentioned below for simplicity - you will find detailed parameter list and snippets in upcoming sections where we discuss detailed implementation steps.
Feature
Description
Android
iOS
Manual trip Start
Provide the user with an option to start trip manually on your application
startTrip()
startManualTrip()
Manual Trip End
Provide user with option to end trip manually on your application
stopTrip()
manualTripEnd()
Automatic Trip Detection Started
Methods to define app function when Kruzr SDK has started drive detection analysis.
onTripDetection
Starting()
detectedNewTrip()
Automatic Trip Detection Confirmed
Methods to define app function when Driving State is confirmed
onTripStarted()
didTripStarted()
Intermediate break in trips
Methods to define app function on "Intermediate" driving stage, i.e. driver has stopped or stuck in traffic jams.
onTripPaused()
didStopDriving()
Restart of ongoing trip after break
In case driver has continued their trip after a short break, we map it into the same trip
onTripResumed()
didResumeDriving()
Automatic Trip End
To identify if trip has completed
onTripEnded()
didTripEnd()
Notification for Driving Detection
Method to control push notifications when driving state is being confirmed
onDriveDetermining
NotificationClick()
Not Available
Notification for Driving State Confirmation
Method to control push notifications when driving state is confirmed
onDriveOngoing
NotificationClick()
Not Available
Notification on Successful Trip Summary Generation
Method to control action on push notification when trip summary is ready for consumption
onDriveSummary
NotificationClick()
Not Available
Getting list of all trips for a user
To receive trip list for a user
fetchTripList()
getAllTrips()
Getting events and data for ongoing trip
To receive trip metrics an ongoing trip
getTripData()
Not Available
Getting events and data for a completed trip
To receive detailed trip events and data for a completed trip
fetchTripDetailByTripId
getTripDetail()
Configure trip data sync process
To set preference between WIFI vs WIFI + Cellular data trip syncs
setDataSyncPref
Not Available
Getting current trip data sync setting
To get the current setting for trip data sync
getCurrentDataSyncPref
Not Available
Set Account Name shown to user in Notification
Define Account Name shown to users within Trip Related Notifications
setAccountName
Not Available
Last updated
Was this helpful?