Android Checklist and FAQ

Integration Checklist

The following is a checklist of integration tests that need to be completed to verify that the integration is working as intended, as applicable:

• Integrate Zendrive SDK v10.0.3. See Start with Android for more information on how to integrate SDK with your application.

• Update the Zendrive SDK keys on the new build.

• Verify if the SDK initialized at user login and signup.

• Verify if the SDK initialized at application startup (if the user is already logged in).

• Verify if you received the success callback from SDK initialization.

• Ensure that SDK initialization failures are handled correctly - a simple setup retry logic should be added and an error should be displayed to the user in case setup never succeeds, even after retries.

• Verify if isSDKSetup is implemented in the application. If this returns False, the Zendrive.setup() method should be called for the user. Verify this scenario for signed in users.

• Ensure that the onDriveEnd and onDriveAnalyzed callbacks are handled correctly on the app and that the UI reflects trip data.

• Verify that SDK teardown is not called from onDestroy or similar lifecycle methods of an activity of the application. Calling teardown in the lifecycle methods of an activity will cause Zendrive to go dormant if someone opens or closes the application temporarily. Zendrive SDK should be explicitly turned off only due to business logic and not due to system-triggered events.

• Verify that the application is subscribed to the BOOT_COMPLETED intent, and that restarting the phone automatically triggers Zendrive setup and any expected Zendrive callbacks. This can be quickly verified by adding some logs to Zendrive callbacks.

• Verify that the application is subscribed to the MY_PACKAGE_REPLACED intent. This intent is needed in case the application is upgraded and is no longer running. Subscribe to the MY_PACKAGE_REPLACED intent and start your application automatically which should trigger Zendrive SDK to reinitialize.

• Ensure that Zendrive Error Codes that come up during Zendrive SDK operations are handled properly. A simple setup retry logic should be added and an error should be displayed to the user in case setup never succeeds, even after retries.

• When the SDK sends the OnZendriveSettingsConfigChanged callback, the application should persist with the values of the errorsFound and warningsFound flags. These flags should be used as a basis to call Zendrive.getZendriveSettings(context, callback) to get a list of errors and warnings on app resume. See Check for Setting Errors and Warnings.

• Verify that uploadAllDebugDataAndLogs is integrated, in order to trigger a bulk upload of all SDK data on the device to Zendrive for debugging purposes. This should happen whenever the user reaches out for support, for example when the user clicks on the Help and Support button on the application or via silent notification sent to the client.

• Verify that the getEventSupportForDevice and isAccidentDetectionSupported methods are called on SDK initialization and an error is displayed to the user if this is false.

• Verify that debugging tools used by the application (such as Crashlytics) are able to log any Zendrive-related successes and errors.

• Verify that you've implemented the methods outlined in Troubleshoot Phone Restrictions to support various OEMs.

Collision Detection Checklist

Use the following checklist to implement the collision detection feature as per your business needs:

1. Test your integration using the triggerMockAccident method. This creates a fake collision and invokes the onAccident handler in the ZendriveBroadcastReceiver. This requires that the SDK is set up and a trip is currently in progress.

2. Invoke the triggerMockAccident method with ZendriveAccidentConfidence.HIGH and verify that the workflow implemented is working as expected.

3. Invoke the triggerMockAccident method with ZendriveAccidentConfidence.LOW and verify that the implemented workflow is working as expected.

4. Help improve Zendrive by providing information about whether a collision event detected by the SDK occurred or not by calling the ZendriveFeedback.addEventOccurrence method.

5. Please refer to the sample workflow for collision detection below and verify that the implementation is as per your business needs. If you use the dual notification system, refer to our full Collision guide.

Best Practices and F.A.Q.

Zendrive SDK will keep detecting trips as long as it’s alive. But there are some cases when it’s not set up properly and it stops detecting trips. Here are some ways you can make sure your application is always running as expected.

1. Resolve all errors and warnings reported by the SDK.

When the SDK sends the OnZendriveSettingsConfigChanged callback, the application should persist the values of the errorsFound and warningsFound flags. These flags should be used as a basis to call Zendrive.getZendriveSettings(context, callback) to get a list of errors and warnings on app resume.

See Check for Settings Errors and Warnings.

2. Don’t use the teardown method in the main activity of your application.

Calling the teardown() method makes the Zendrive SDK go dormant. This causes a problem for background tracking. The features implemented to wake up the SDK in the background for tracking will all be disabled. So, when your app gets killed by the OS and onDestroy() calls SDK teardown, the Zendrive SDK cannot be restarted in the background for tracking till the app is restarted again.

The teardown method should be called only when you want to explicitly turn off Zendrive for a user in your app's business logic and not let it be triggered by system events.

3. Obtain user consent for displaying notifications during installation.

On Android 13, user consent is required to post notifications during runtime. Zendrive SDK runs a foreground service while a trip is on, that comes with an associated notification, which requires Android's runtime permission to be enabled. Enabling this permission is very essential as runtime notifications help improve user engagement. The following references provide information on the impact of this permission during runtime.

• Effect of this permission on newly installed apps

• Effect on upgrades to existing apps

Recommended action: Build a notification permission dialogue box through which to obtain user consent for displaying notifications at the time of installation.

3. Make sure users enable High Accuracy Location on their device.

It is quite common for users to turn off High Accuracy Location on their device to conserve battery. However, Zendrive automatic trip detection requires it to be on. Applications should ask the user to turn on High Accuracy Location through a friendly explanatory message. This is an error reported via the OnZendriveSettingsConfigChanged callback.

See Google documentation for information. Also see Check for Settings Errors and Warnings.

4. Avoid battery saver mode

Battery Saver mode prevents the SDK from detecting trips on most Android phones starting from Android 9 (API level 28). Activating the battery saver mode leads to the interruption of ongoing trips, as it affects location services. We recommend that you alert the users to not run Battery Saver mode when they turn it on.

Battery Saver mode is reported as an error or warning (depending on whether trip detection is affected) via the OnZendriveSettingsConfigChanged callback.

See Check for Settings Errors and Warnings.

5. Prevent background restriction

Background restrictions were introduced in Android Pie. If the user enables background restrictions on the application, Zendrive SDK cannot go into foreground mode and therefore will not be able to detect trips. Background restriction is reported as an error via the OnZendriveSettingsConfigChanged callback See Check for Settings Errors and Warnings for more information.

6. Keep 12 Slots free in WorkManager

WorkManager schedules only a limited number of tasks at any given time. Zendrive SDK can schedule up to 12 tasks for various things to do in the background. By default, WorkManager has 20 slots to schedule tasks.

Please make sure your application keeps 12 slots free to ensure that Zendrive SDK works correctly. You can increase the number of slots to 50 using Configuration.Builder.setMaxSchedulerLimit(int).

7. Subscribe to the BOOT_COMPLETED intent

Whenever a phone dies and restarts, your application is no longer running unless the user explicitly starts it. You can start your application automatically by subscribing to the BOOT_COMPLETED system broadcast intent. See the BootReceiver in this sample project. This requires your application to be granted an additional permission.

8. Subscribe to the MY_PACKAGE_REPLACED intent

This intent is broadcast whenever your application is upgraded. After an upgrade, your application is no longer running (just like during device restart). You can subscribe to this intent and handle it the same way as the BOOT_COMPLETED intent. See this sample project.

9. Using Android App Bundles

Since the SDK packages the native libraries for the top ABIs, all the native libraries get packaged into the final APK of the application as well. If this size increase is a concern, you can take some of the following measures to reduce the size of the APK.

Use Android App Bundles, which allows users to download only parts of the application that are relevant to them. It includes downloading only one variant of the various ABIs that are shipped with the SDK.

10. Upload debug data

Debug data helps us improve Zendrive SDK. Your application should contain a prompt or a CTA for the user to upload debug data. Call the function below to send a debug report of the current driver to Zendrive. Zendrive SDK will create a background task to ensure the completion of this upload task.

Zendrive.uploadAllDebugDataAndLogs();

Frequently Asked Questions

1. Do I need to implement all the callbacks in ZendriveBroadcastReceiver?

Strictly speaking, no. If you only want to collect and track data, you do not need to implement the callbacks. However, if you have any business logic you want to apply, we strongly recommend doing it within the methods we provide.

2. What app permissions are required to use Zendrive SDK?

Starting with API 23, the user needs to explicitly grant your application the ACCESS_FINE_LOCATION permission at runtime. Your application should provide this permission before calling Zendrive.setup().

The SDK reports the missing permission as an error via the onZendriveSettingsConfigChanged Callback. See Check for Setting Errors and Warnings for more information.

If the user denies ACCESS_FINE_LOCATION, Zendrive SDK will switch to a dormant state. The SDK will stay initialized, but will remain dormant till the permission is granted again.

3. How does the SDK decide when it needs to run in the foreground?

Android Oreo imposes various restrictions on apps running in the background around execution and location. To work correctly under such restrictions, Zendrive may run in the foreground even outside of drives.

When the SDK needs to be promoted to the foreground during the drive detection phase, it calls the ZendriveNotificationProvider.getMaybeInDriveNotificationContainer() method. This method is called only on phones running Android Oreo or newer. When a drive is detected, the SDK replaces the notification with the ZendriveNotificationProvider.getInDriveNotificationContainer() method.