com.zendrive.sdk

Class Zendrive

java.lang.Object

com.zendrive.sdk.Zendrive

public abstract class Zendrive
extends Object

Zendrive class is the entry point into the Zendrive SDK.

This is the typical usage:

 
  public class MyActivity extends Activity {
      ...
      static final String ZENDRIVE_SDK_KEY_STRING = ...
      ...


      public void setupZendriveSDK(View v){
          ...
          ZendriveConfiguration zendriveConfiguration = new ZendriveConfiguration(
               ZENDRIVE_SDK_KEY_STRING, driverId);
          Zendrive.setup(this.getApplicationContext(),
              zendriveConfiguration, MyZendriveBroadcastReceiver.class,
              MyZendriveNotificationProvider.class,
              new ZendriveOperationCallback() {
                   @Override
                  public void onCompletion(ZendriveOperationResult result) {
                      if (result.isSuccess()) {
                          Log.d(MY_APP_TAG, "Zendrive is setup.");
                      }
                  }
              }
          );
      }
      ...
  }
 
 

Other than setup, all methods are optional to call by the application. They are also no-ops in case setup has not been called. All methods are threadsafe.

Method Summary

Modifier and Type	Method and Description
static ActiveDriveInfo	getActiveDriveInfo(Context context) Get info on the currently active drive.
static ZendrivePauseAutoTrackingReason	getAutoTrackingPauseReason(Context context) Use this method to get the ZendrivePauseAutoTrackingReason when the auto tracking is paused.
static String	getBuildVersion() Returns an identifier which can be used to identify this SDK build.
static Map<ZendriveEventType,Boolean>	getEventSupportForDevice(Context context) Check whether the zendrive event types are supported or not on this device
static void	getInternalDriveType(Context context, long timestamp, ZendriveInternalDriveTypePreviewCallback callback) Get the internal drive type ZendriveInternalDriveTypePreview for a given drive.
static void	getZendriveSettings(Context context, ZendriveSettingsCallback callback) Get the current state of settings affecting the Zendrive SDK's normal operation.
static void	getZendriveState(Context context, ZendriveStateCallback callback) Get the current state of the Zendrive SDK.
static boolean	isAccidentDetectionSupported(Context context) Is Zendrive collision detection supported on this device?
static boolean	isAutoTripTrackingPaused(Context context) Use this method to check if auto trip tracking has been paused.
static boolean	isSDKSetup(Context context) Is the Zendrive SDK already setup?
static boolean	isValidInputParameter(String input) Checks whether the string passed to the SDK is valid.
static ZendrivePauseAutoTrackingResult	pauseAutoTracking(Context context, Long pausedTillTimestamp) Use this method to pause the SDK for a limited duration.
static void	refreshBusinessHours(Context context, ZendriveRefreshBusinessHoursCallback callback) Refreshes the business hours set by the fleet manager, instantly.
static ZendriveResumeAutoTrackingResult	resumeAutoTracking(Context context) Use this method to resume the SDK immediately.
static void	setup(Context context, ZendriveConfiguration zendriveConfiguration, Class<? extends ZendriveBroadcastReceiver> broadcastReceiverClass, Class<? extends ZendriveNotificationProvider> notificationProviderClass, ZendriveOperationCallback callback) Setup the Zendrive SDK with a configuration and a intent service for SDK callbacks.
static void	setZendriveDriveDetectionMode(Context context, ZendriveDriveDetectionMode driveDetectionMode, ZendriveOperationCallback callback) Use this method to change the ZendriveDriveDetectionMode after SDK is already setup.
static void	startDrive(Context context, String trackingId, ZendriveOperationCallback callback) Manually start recording a drive.
static ZendriveOperationResult	startSession(Context context, String sessionId) Start a session in the SDK.
static void	stopManualDrive(Context context, ZendriveOperationCallback callback) Stop the currently active manually started drive.
static ZendriveOperationResult	stopSession(Context context) Stop currently ongoing session.
static void	teardown(Context context, ZendriveOperationCallback callback) Shuts down the Zendrive framework.
static void	triggerMockAccident(Context context, ZendriveAccidentConfidence confidence, ZendriveOperationCallback callback) Triggers a fake accident.
static void	triggerMockAccident(Context context, ZendriveMockAccidentConfiguration configuration, ZendriveOperationCallback callback) Triggers a fake accident.
static ZendriveOperationResult	uploadAllDebugDataAndLogs(Context context) Allows an application to trigger a bulk upload of all SDK data on the device to Zendrive for debugging purposes.
static void	wipeOut(Context context, ZendriveOperationCallback callback) Wipe out all the data that zendrive keeps locally on the device.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setup

public static void setup(@NonNull
                         Context context,
                         @NonNull
                         ZendriveConfiguration zendriveConfiguration,
                         @Nullable
                         Class<? extends ZendriveBroadcastReceiver> broadcastReceiverClass,
                         Class<? extends ZendriveNotificationProvider> notificationProviderClass,
                         @Nullable
                         ZendriveOperationCallback callback)

Setup the Zendrive SDK with a configuration and a intent service for SDK callbacks.

This will start tracking the phone's movements to track any driving activity. The application should call this method before anything else in the Zendrive SDK.

Calling this method multiple times with the same 'sdkKey' and 'driverId' in the ZendriveConfiguration is a no-op. If provided, the ZendriveBroadcastReceiver class will be sent SDK callbacks after the call. If either the 'sdkKey' or 'driverId' in the ZendriveConfiguration changes between the previous setup call and this one, it will be the same as calling teardown(android.content.Context, com.zendrive.sdk.ZendriveOperationCallback) followed by calling setup with the new parameters.

Once setup finishes, the ZendriveOperationCallback is called (if provided) with the result of the setup operation. Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

Parameters:

context - is the context object of the enclosing application.

zendriveConfiguration - The configuration properties to setup the Zendrive SDK. Cannot be null.

broadcastReceiverClass - A intent service which receives callbacks from the SDK. It receives updates about interesting events like start and end of a drive, accident detected etc from the SDK. Specify null if you don't want to receive callbacks from the SDK.

notificationProviderClass - A ZendriveNotificationProvider class that is used to fetch notifications when the sdk goes foreground.

callback - The callback to be invoked after setup. It will be invoked on the same thread where setup is called. This can be null if no callback is desired by the application.

teardown

public static void teardown(@NonNull
                            Context context,
                            @Nullable
                            ZendriveOperationCallback callback)

Shuts down the Zendrive framework. This may be called if the client code wishes to turn off the Zendrive framework to isolate the operations that the application is doing.

This is a no-op if setup(android.content.Context, com.zendrive.sdk.ZendriveConfiguration, java.lang.Class<? extends com.zendrive.sdk.ZendriveBroadcastReceiver>, java.lang.Class<? extends com.zendrive.sdk.ZendriveNotificationProvider>, com.zendrive.sdk.ZendriveOperationCallback) has not been called.

Once teardown finishes, the ZendriveOperationCallback is called (if provided) with the result of the teardown operation. Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

N.B. the library is typically very conservative about what modules of the phone it uses for tracking and how much memory it uses etc. and as such is very conservative about memory and battery impact. So this method should not really be called to save power/memory for the application.

setZendriveDriveDetectionMode

public static void setZendriveDriveDetectionMode(@NonNull
                                                 Context context,
                                                 @NonNull
                                                 ZendriveDriveDetectionMode driveDetectionMode,
                                                 @Nullable
                                                 ZendriveOperationCallback callback)

Use this method to change the ZendriveDriveDetectionMode after SDK is already setup. Applications which do not want the SDK to continuously track drives in background should set this value to AUTO_OFF. With this, the application needs to call startDrive(android.content.Context, java.lang.String, com.zendrive.sdk.ZendriveOperationCallback) method to record drives. In case the application wants to enable auto drive detection only for a fixed duration (like when the driver is on-duty), use this method to change the mode to AUTO_ON for that period and set it back to AUTO_OFF (once the driver goes off-duty).

Once setup finishes, the ZendriveOperationCallback is called (if provided) with the result of the setup operation. Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

Parameters:

driveDetectionMode - The new drive detection mode. If this is the same as the current ZendriveDriveDetectionMode, then this call is a no-op.

callback - called with the result of the operation when completed. In case of any error encountered, the result contains the relevant error details.

startDrive

public static void startDrive(@NonNull
                              Context context,
                              @Nullable
                              String trackingId,
                              @Nullable
                              ZendriveOperationCallback callback)

Manually start recording a drive.

For applications which want to manually start recording drives(as opposed to automatic detection that the framework does) this method may be called.

Any auto-detected drives in progress will be terminated and a new drive will be started at this time.

The 'trackingId' will eventually show up in the reports that Zendrive generates.

When this method is called it is the client code's responsibility to call stopManualDrive(android.content.Context, com.zendrive.sdk.ZendriveOperationCallback) to indicate the end of the drive. These methods should be used when the application has explicit knowledge of the start and end of a drive. In such applications, using this call is recommended).

When startDrive is called with a manually recorded drive in progress, if trackingId matches the ongoing drive's trackingId, this call is a no-op. If the trackingIds do not match, stopManualDrive(android.content.Context, com.zendrive.sdk.ZendriveOperationCallback) is called implicitly before a new drive is started.

Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

Parameters:

trackingId - Optional identifier which allows identifying this drive uniquely. If this value is null, the SDK will supply a default trackingId with value com.zendrive.sdk.internal . It may not be an empty string. It will be truncated to 64 characters if it is longer than 64 characters. Passing invalid trackingId is an error.

callback - called with the result of the operation

stopManualDrive

public static void stopManualDrive(@NonNull
                                   Context context,
                                   @Nullable
                                   ZendriveOperationCallback callback)

Stop the currently active manually started drive.

The startDrive(android.content.Context, java.lang.String, com.zendrive.sdk.ZendriveOperationCallback) and stopManualDrive calls are not counted. i.e stopManualDrive will stop a manually started drive irrespective of how many times startDrive(android.content.Context, java.lang.String, com.zendrive.sdk.ZendriveOperationCallback) is called.

This call has no effect on an automatically detected drive that may be in progress.

Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

Parameters:

callback - called with the result of the operation when completed

startSession

public static ZendriveOperationResult startSession(@NonNull
                                                   Context context,
                                                   @NonNull
                                                   String sessionId)

Start a session in the SDK.

Applications which want to record several user's drives as a session may use this call. All drives (automatically detected or manually started) when a session is in progress will be tagged with the session id. If a drive is already on when this call is made, that drive will not belong to this session. This session id will be made available in the reports and API that Zendrive provides.

The application must call stopSession(android.content.Context) when it wants to end the session.

Only one session may be active at a time. Calling startSession when a session is already active will terminate the ongoing session and start a new one with the given id.

Parameters:

sessionId - an identifier that identifies this session uniquely. It may not be null or an empty string. It may not be longer than 64 characters. Passing invalid sessionId is a no-op.

Returns:

the result of the startSession operation.

stopSession

public static ZendriveOperationResult stopSession(@NonNull
                                                  Context context)

Stop currently ongoing session. No-op if no session is ongoing. Trips that start after this call do not belong to the session. Ongoing trips at the time of this call will continue to belong to the session that was just stopped.

Returns:

the result of the stopSession operation.

See Also:

startSession(android.content.Context, java.lang.String)

isValidInputParameter

public static boolean isValidInputParameter(@Nullable
                                            String input)

Checks whether the string passed to the SDK is valid.

String parameters cannot be null or empty. Unless documented otherwise, strings parameters to the SDK cannot contain any of the following characters - "?", " ", "&", "/", "\", ";", "#", "\n"

Parameters:

input - The string to validate

Returns:

true if the string is valid, false otherwise

isSDKSetup

public static boolean isSDKSetup(@NonNull
                                 Context context)

Is the Zendrive SDK already setup?

Returns:

true if Zendrive SDK is already setup. Else false.

triggerMockAccident

public static void triggerMockAccident(@NonNull
                                       Context context,
                                       @NonNull
                                       ZendriveAccidentConfidence confidence,
                                       @Nullable
                                       ZendriveOperationCallback callback)

Triggers a fake accident.

A fake accident will be invoked on the ZendriveListener after this function is called. Requires that the Zendrive SDK is setup and a trip is in progress.

This function can be used to test the accident detection integration of your application.

Once setup finishes, the ZendriveOperationCallback is called (if provided) with the result of the setup operation. Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

Parameters:

context - is the context object of the enclosing application

confidence - is the confidence level of the accident to trigger

callback - called with the result of the operation when completed. In case of any error encountered, the result contains the relevant error details.

See Also:

triggerMockAccident(Context, ZendriveMockAccidentConfiguration, ZendriveOperationCallback)

triggerMockAccident

public static void triggerMockAccident(@NonNull
                                       Context context,
                                       @NonNull
                                       ZendriveMockAccidentConfiguration configuration,
                                       @Nullable
                                       ZendriveOperationCallback callback)

Triggers a fake accident.

A fake accident will be invoked on the ZendriveListener after this function is called. Requires that the Zendrive SDK is setup and a trip is in progress.

This function can be used to test the accident detection integration of your application.

Once setup finishes, the ZendriveOperationCallback is called (if provided) with the result of the setup operation. Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

Parameters:

context - is the context object of the enclosing application

configuration - is the configuration object defining the details of the collision

callback - called with the result of the operation when completed. In case of any error encountered, the result contains the relevant error details.

See Also:

triggerMockAccident(Context, ZendriveMockAccidentConfiguration, ZendriveOperationCallback)

getBuildVersion

public static String getBuildVersion()

Returns an identifier which can be used to identify this SDK build.

isAccidentDetectionSupported

public static boolean isAccidentDetectionSupported(@NonNull
                                                   Context context)

Is Zendrive collision detection supported on this device?

Returns:

true if zendrive collision detection is supported on this device.

getEventSupportForDevice

public static Map<ZendriveEventType,Boolean> getEventSupportForDevice(@NonNull
                                                                      Context context)

Check whether the zendrive event types are supported or not on this device

Returns:

a map where for each zendrive event type, there is a boolean indicating if it is supported or not.

uploadAllDebugDataAndLogs

public static ZendriveOperationResult uploadAllDebugDataAndLogs(@NonNull
                                                                Context context)

Allows an application to trigger a bulk upload of all SDK data on the device to Zendrive for debugging purposes. This uploads historical data and logs on the device.

WARNING: This will cause significant battery drain on the device. It will also use significant upload bandwidth to upload this data..

This is meant to be used sparingly by applications. This should be used only when you have raised a ticket with Zendrive and Zendrive support recommends this approach to debug the issue.

wipeOut

public static void wipeOut(@NonNull
                           Context context,
                           @Nullable
                           ZendriveOperationCallback callback)

Wipe out all the data that zendrive keeps locally on the device.

When Zendrive SDK is torn down, trip data that is locally persisted continues to remain persisted. The data will be uploaded when SDK setup is called at a later time. Wipeout should be used when the application wants to remove all traces of Zendrive on the device. Data cannot be recovered after this call.

NOTE: This call can be made when the SDK is not running. Call teardown(android.content.Context, com.zendrive.sdk.ZendriveOperationCallback) to tear down a live SDK before making this call.

Callback will be made on calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

Parameters:

context - The context of the enclosing application.

callback - Called with the result of the operation.

getActiveDriveInfo

public static ActiveDriveInfo getActiveDriveInfo(@NonNull
                                                 Context context)

Get info on the currently active drive. If sdk is not setup or if no drive is in progress, null is returned.

Returns:

Info about the currently active drive or null.

getZendriveState

public static void getZendriveState(@NonNull
                                    Context context,
                                    @NonNull
                                    ZendriveStateCallback callback)

Get the current state of the Zendrive SDK.

Parameters:

context - The context of the enclosing application.

callback - The callback that is used to send the ZendriveState object back to the application.

getZendriveSettings

public static void getZendriveSettings(@NonNull
                                       Context context,
                                       @NonNull
                                       ZendriveSettingsCallback callback)

Get the current state of settings affecting the Zendrive SDK's normal operation.

If the SDK is set up, this async method returns a ZendriveSettings object that contains a list of errors and warnings that are affecting Zendrive's ability to detect trips and perform other tasks.

If the SDK is not set up, the ZendriveSettings object returned is NULL.

The application should call this method when the SDK reports errors via the ZendriveBroadcastReceiver.onZendriveSettingsConfigChanged(Context, boolean, boolean) callback. All errors must be resolved by the application before trip detection can continue.

Parameters:

context - The context of the enclosing application.

callback - The callback that is used to send the ZendriveSettings object back to the application.

pauseAutoTracking

public static ZendrivePauseAutoTrackingResult pauseAutoTracking(@NonNull
                                                                Context context,
                                                                @NonNull
                                                                Long pausedTillTimestamp)

Use this method to pause the SDK for a limited duration. Applications which do not want the SDK to track drives in background should call this method. In case the SDK is paused and teardown(android.content.Context, com.zendrive.sdk.ZendriveOperationCallback) is called, SDK is resumed on next setup.

Call resumeAutoTracking(android.content.Context) to resume the SDK immediately.

Parameters:

pausedTillTimestamp - The Epoch millisecond value of time till which SDK needs to be paused.

resumeAutoTracking

public static ZendriveResumeAutoTrackingResult resumeAutoTracking(@NonNull
                                                                  Context context)

Use this method to resume the SDK immediately. Applications which want the SDK to start tracking drives immediately should use this. Call to this method is a no op if the SDK is not paused.

Call pauseAutoTracking(android.content.Context, java.lang.Long) to pause SDK from tracking drives for a limited duration.

isAutoTripTrackingPaused

public static boolean isAutoTripTrackingPaused(@NonNull
                                               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.

Call pauseAutoTracking(android.content.Context, java.lang.Long) to pause the SDK from tracking drives for a limited duration. Call resumeAutoTracking(android.content.Context) to resume the SDK's tracking immediately.

refreshBusinessHours

public static void refreshBusinessHours(@NonNull
                                        Context context,
                                        @NonNull
                                        ZendriveRefreshBusinessHoursCallback callback)

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.

If the SDK is set up, a ZendriveShiftDetail object is returned along with the ZendriveBusinessHoursOperationResult result via the ZendriveRefreshBusinessHoursCallback callback. Callback is made on the calling thread if it's Looper is already prepared, else the callback is made on the Main Thread.

The ZendriveShiftDetail object returned is NULL in the following cases:
a. the SDK is not set up.
b. the business hours feature is not enabled for the application.
c. network unavailability.
d. internal error while making the network call to the server.

All the above cases map to a unique ZendriveBusinessHoursOperationResult result code.

Parameters:

context - The context of the enclosing application.

callback - The callback used to provide ZendriveShiftDetail back to the application.

getAutoTrackingPauseReason

public static ZendrivePauseAutoTrackingReason getAutoTrackingPauseReason(Context context)

Use this method to get the ZendrivePauseAutoTrackingReason when the auto tracking is paused.

If the SDK is not set up, the ZendrivePauseAutoTrackingReason object returned is NULL.

Otherwise, ZendrivePauseAutoTrackingReason.USER is returned if the auto tracking is paused as a result of a call to pauseAutoTracking(Context, Long) and ZendrivePauseAutoTrackingReason.BUSINESS_HOURS is returned if the auto tracking is paused outside the business hours.

In case, the auto tracking is not paused, ZendrivePauseAutoTrackingReason.SDK_NOT_PAUSED is returned.

NOTE: The applications can call isAutoTripTrackingPaused(Context) before calling this API to know the auto tracking pause status of the SDK.

Parameters:

context - The context of the enclosing application.

getInternalDriveType

public static void getInternalDriveType(@NonNull
                                        Context context,
                                        long timestamp,
                                        @NonNull
                                        ZendriveInternalDriveTypePreviewCallback callback)

Get the internal drive type ZendriveInternalDriveTypePreview for a given drive. This is a preview API and its usage should be restricted to experimental purpose.
The drive type is returned via the ZendriveInternalDriveTypePreviewCallback callback. The callback is made on the calling thread if its Looper is already prepared, else the callback is made on the Main thread.
NOTE: This API should be called when the application receives the ZendriveBroadcastReceiver.onDriveAnalyzed(Context, AnalyzedDriveInfo) callback. If called before or at a later point in time, the drive type returned is null.

Parameters:

context - The context of the enclosing application

timestamp - The timestamp of the drive which is DriveInfo.startTimeMillis

callback - The callback to provide ZendriveInternalDriveTypePreview