Trip Detection and Tracking

Zendrive SDK's primary function is to track trips using your phone sensors. This enables a host of other features such as collision notification and driving behavior analysis.

Automatic Trip Detection

Zendrive SDK employs automatic trip detection by default. If the device has cellular data and location on, the SDK wakes up when the user starts driving and begins tracking trip information. When the user stops driving, the SDK recognizes that a trip has ended, and stops tracking information. If the user stops moving for 5 minutes, a trip is assumed to have ended and trip tracking stops.

Manual Trip Detection

For applications that know the extent of their trips and want fine-grain control, Zendrive SDK can be easily configured to manually start and stop trips. In this case, trips will not be automatically detected or interrupted by the SDK. Manual trip detection is useful for ride-sharing apps such as Uber and Lyft and courier services such as Postmates and DoorDash.

Enable Manual Trip management

Use the following methods to manually start and stop trips:

Zendrive.startManualDrive("tracking-id") { (success: Bool, error: Error?) in
    print("Manual Start Drive Call Completed !");
}

Zendrive.stopManualDrive { (success, error) in
    print("Manual Stop Drive Call Completed !");            
}

Your application can then use the <TRACKING_ID> argument to find Zendrive trips with this ID in Zendrive Analytics.

Trip Start Enhancements

(Android only) Bluetooth Trip Start

Starting with iOS SDK 7.1, you can use a bluetooth car stereo to associate the user's car with their mobile device. When the user starts up their car, the bluetooth connection with the car stereo is reestablished and the SDK starts detecting possible trips.

This feature requires the user to set up and associate their vehicles with their mobile device. See Vehicle Tagging to understand this feature.

The benefit of this feature is that there is zero latency in automatic trip detection, and you capture any mileage missed at the start of a trip. If you have pay-per mile programs, this premium feature is useful to you. Contact [email protected] to get started.

Once this feature is enabled for your use, toggle the Boolean enabledBluetoothTripStart key in the ZendriveConfiguration object. The Zendrive SDK will begin using the car stereo of associated vehicles to initiate trip detection.

(iOS and Android) Beacon Trip Start

Starting with iOS SDK 7.1 and Android SDK 8.2, you can use a bluetooth beacon to associate the user's car with their mobile device. When the user sits in their car, the bluetooth connection with the beacon is reestablished and the SDK starts detecting possible trips.

This feature requires the user to set up and associate their vehicles with their mobile device. See Vehicle Tagging to understand this feature.

The benefit of this feature is that there is zero latency in automatic trip detection, and you capture any mileage missed at the start of a trip. If you have pay-per mile programs, this premium feature is useful to you. Contact [email protected] to get started.

Trip Start Extrapolation

Starting with SDK v8.0, the Zendrive SDK (on iOS and Android) uses the end location of a trip as the start location of the next trip. In practice, a drive may be detected only after a short distance is covered. The Zendrive SDK will extrapolate the distance between that location and the location where the drive is detected.

Trip start extrapolation is useful for calculating accurate miles driven. If you have pay-per-mile programs, this feature can help you get the most out of the Zendrive SDK's trip detection.

Requirements:

  • This feature only enhances automatic trip detection. It does not affect trips started manually.

  • This feature has a threshold of 1.6km, beyond which it does not calculate extrapolated distance.

  • Driving behavior events and scores will not be calculated for the extrapolated distance.

  • If you've set up vehicle tagging, trip start extrapolation will be implemented for two consecutive tagged trips.

Using this Feature

Trip start extrapolation is enabled by default for all our customers. The extra distance is captured in a new ExtrapolationDetails field in the DriveInfo class as shown below.

public class ExtrapolationDetails {
+    public var reportedDistance : Double
+    public var estimatedStartLocation: LocationPoint
}

This field is optional and is calculated separately. By default, it does not affect the trip distance of your users. You may use the extrapolated distance and add it to the trip mileage. In either case, scores and events will not be affected for the extrapolated distance, as shown in the following screenshot:

Extrapolated distance will be displayed on the trip map as a visually distinct line, as shown in the following screenshot:

Pause Auto Tracking

Zendrive SDK automatically tracks user’s driving patterns in the background. However, users can pause automatic trip tracking for a specified duration, both in the Personal Lines and Commercial Lines space.

In both cases, once the pause duration is over, the SDK automatically resumes tracking the trip. The Pause Auto Tracking feature enables the user to take a few hours or a few days off of his or her work schedule.

For Personal Lines

In the Personal Lines space, the user who drives the vehicle decides when to pause tracking. Usually this is done to enjoy a few hours or days of privacy. When auto trip tracking is on, if the user pauses the trip, then SDK does not record the pause trip data. However, if the Manual Tracking mode is on when automatic tracking is paused, SDK goes ahead and records the trip data for the pause duration.

For Commercial Lines

Zendrive introduces the concept of Privacy and Business Hours to accommodate both the fleet manager's goals, and the user's need for personal time off during business hours. The fleet manager determines the Business Hours during which Zendrive SDK is supposed to track trips for a given fleet. These Business Hours could vary from fleet to fleet, depending on the fleet manager's needs. The fleet manager can track users only within the stipulated Business Hours timeframe. During the set Business Hours, fleet drivers can still pause tracking for personal reasons.

The following image illustrates the utility of Pause Tracking in Personal Lines and Privacy and Business Hours in Commercial Lines:

The following diagram provides a high-level overview of the Business Hours function for the Commercial Lines space.

Pause Tracking APIs

The following APIs enable you to set up the Pause Auto Tracking feature with SDK.

1. pauseAutoTracking API

When the user opts to pause auto tracking, the pauseAutoTracking request API is initiated. Automatic trip detection by the SDK will be paused till pausedTillTimestamp which will be provided as part of the parameter

 /**
     * Use this method to check if auto trip tracking has been paused. All manual trips will
     * continue to be recorded in the pause state.
     * Returns true if SDK is not setup.
     *
     * <p>
     * Call {@link Zendrive#pauseAutoTracking} to pause the SDK from tracking drives for a limited
     * duration.
     * Call {@link Zendrive#resumeAutoTracking} to resume the SDK's tracking immediately.
     */

2. resumeAutoTracking

SDK automatically launches the resumeAutoTracking request after the pauseTillTimestamp pause auto tracking period parameter is satisfied.

/**
     * Use this method to check if auto trip tracking has been paused. All manual trips will
     * continue to be recorded in the pause state.
     * Returns true if SDK is not setup.
     *
     * <p>
     * Call {@link Zendrive#pauseAutoTracking} to pause the SDK from tracking drives for a limited
     * duration.
     * Call {@link Zendrive#resumeAutoTracking} to resume the SDK's tracking immediately.
     */

3. isAutoTrackingPaused

This API validates the success of isAutoTrackingPaused request and returns the current status of SDK's auto tracking.

/**
     * Use this method to check if auto trip tracking has been paused. All manual trips will
     * continue to be recorded in the pause state.
     * Returns true if SDK is not setup.
     *
     * <p>
     * Call {@link Zendrive#pauseAutoTracking} to pause the SDK from tracking drives for a limited
     * duration.
     * Call {@link Zendrive#resumeAutoTracking} to resume the SDK's tracking immediately.
     */
    public synchronized static boolean isAutoTripTrackingPaused(@NonNull Context context) {
        return ZendriveImpl.isAutoTripTrackingPaused(context);
    }

Business Hours APIs

The Commercial Lines Fleet Manager sets or modifies Business Hours. The set Business Hours don't reflect on the Zendrive SDK, either after every trip or at any appropriate time. Customers need to call the refreshBusinessHours API to obtain the latest pause auto trip tracking information. Users can resume auto trip tracking before the pause auto tracking duration is complete. In such cases, SDK automatically resumes tracking the trip.

We advise customers to call the refreshBusinessHours API only when required, as frequent usage can deplete device battery.

1. refreshBusinessHours API

/**
     * Refreshes the business hours set by the fleet manager, instantly. When this API is called,
     * the SDK makes a network call to the backend to fetch and update the business hours.
     * <p>
     * If the SDK is set up, a {@link ZendriveShiftDetail} object is returned along with the
     * {@link ZendriveBusinessHoursOperationResult} result via the
     * {@link ZendriveRefreshBusinessHoursCallback} callback. Callback is made on the calling thread
     * if it's {@link android.os.Looper} is already prepared, else the callback is made on the
     * Main Thread.
     * <p>
     * The {@link ZendriveShiftDetail} object returned is NULL in the following cases:
     * <br> a. the SDK is not set up.
     * <br> b. the business hours feature is not enabled for the application.
     * <br> c. network unavailability.
     * <br> d. internal error while making the network call to the server.
     * <p>
     * All the above cases map to a unique {@link ZendriveBusinessHoursOperationResult} result code.
     *
     * @param context       The context of the enclosing application.
     * @param callback      The callback used to provide {@link ZendriveShiftDetail} back to the
     *                      application.
     */
     public synchronized static void refreshBusinessHours(@NonNull Context context,
                                                         @NonNull ZendriveRefreshBusinessHoursCallback callback) 
   /**
     * The latest business hours have been successfully fetched.
     */
    SUCCESS("Fetched latest business hours successfully."),

    /**
     * The {@link Zendrive#refreshBusinessHours} operation failed because the SDK is not setup.
     */

    SDK_NOT_SETUP("Refresh business hours called before SDK setup"),
    /**
     * The business hours feature is currently not enabled. Please contact "[email protected]"
     * to get the feature enabled.
     */

    BUSINESS_HOURS_NOT_ENABLED("The business hours feature is not enabled."),
    /**
     * Network connectivity is unavailable or is flaky. Try again after connecting the device to
     * a reliable network
     */

    NO_NETWORK("Unable to refresh business hours. The network connectivity is unavailable or flaky. Please try again after connecting the device to a reliable network"),
    /**
     * The refresh business hours request is timed out. Please contact "[email protected]"
     * support if the problem persists.
     */

    REQUEST_TIMEOUT("The request has timed out.");

2. kogetPauseReason API

/**
     * Use this method to get the {@link ZendrivePauseAutoTrackingReason} when the auto tracking
     * is paused.
     * <p>
     * If the SDK is not set up, the {@link ZendrivePauseAutoTrackingReason} object returned is NULL.
     * <p>
     * Otherwise, {@link ZendrivePauseAutoTrackingReason#USER} is returned if the auto tracking is
     * paused as a result of a call to {@link Zendrive#pauseAutoTracking(Context, Long)} and
     * {@link ZendrivePauseAutoTrackingReason#BUSINESS_HOURS} is returned if the auto tracking is
     * paused outside the business hours.
     * <p>
     * In case, the auto tracking is not paused,
     * {@link ZendrivePauseAutoTrackingReason#SDK_NOT_PAUSED} is returned.
     *
     * <p><b> NOTE: The applications can call {@link Zendrive#isAutoTripTrackingPaused(Context)}
     * before calling this API to know the auto tracking pause status of the SDK.
     *
     * @param context   The context of the enclosing application.
     *
     */
    public synchronized static ZendrivePauseAutoTrackingReason getAutoTrackingPauseReason(
            Context context)
            /**
     * Use this method to check if auto trip tracking has been paused. All manual trips will
     * continue to be recorded in the pause state.
     * Returns true if SDK is not setup.
     *
     * <p>
     * Call {@link Zendrive#pauseAutoTracking} to pause the SDK from tracking drives for a limited
     * duration.
     * Call {@link Zendrive#resumeAutoTracking} to resume the SDK's tracking immediately.
     */
    public synchronized static boolean isAutoTripTrackingPaused(@NonNull Context context) {
        return ZendriveImpl.isAutoTripTrackingPaused(context);
    }

3. businessHoursChanged Callback API

Zendrive SDK uses this app to notify the customer app of any changes in Business Hours specification.

/**
     * Called whenever the business hours are fetched and updated by the Zendrive SDK.
     * <p>
     * <b>NOTE: To get the updated business hours instantly, the application must call
     * {@link Zendrive#refreshBusinessHours(Context, ZendriveRefreshBusinessHoursCallback)}.
     *
     * @param context               The Context in which the receiver is running.
     * @param zendriveShiftDetail   Information about the updated business hours represented by the
     *                              {@link ZendriveShiftDetail} object.
     */

Was this helpful?