Best Practices and F.A.Q

Zendrive SDK will keep detecting trips as long as it’s alive. However, if the SDK is not set up properly, it will stop detecting trips. Here are some ways you can make sure your application is always running as expected.

Zendrive Module Promises

The RN bridge is asynchronous by design. All the methods that bridge to RN SDK are returned as promises. We highly recommended that you resolve these promises promptly, and handle all cases, using one of the following methods, or a combination of both:

1. Chaining with then, catch and finally

For example, the setup method returns a promise upon invocation. Your code snippet should look something like this:

Zendrive.setup({
  driverId: '<your-driver-id>',
  sdkKey: '<your-sdk-key>',
})
  .then(result => {
    // check for success
    if (result.isSuccess) {
      // go ahead with business logic
    } else {
      // check for result.errorMessage & result.errorCode and take appropriate actions
    }
  })
  .catch(error => {
    // handle unexpected scenario.
  })
  .finally(() => {
    // optional -- do necessary cleanup if needed
  });

2. Using async/await

Here we are continuing with the same setup method example as above. With the async/await pattern, the same code can be written as follows:

try {
  const result = await Zendrive.setup({
    driverId: '<your-driver-id>',
    sdkKey: '<your-sdk-key>',
  });
  // check for success
  if (result.isSuccess) {
    // go ahead with business logic
  } else {
    // check for result.errorMessage & result.errorCode and take appropriate actions
  }
} catch (error) {
  // handle unexpected scenario.
} finally {
  // optional -- do necessary cleanup if needed
}

Handling Events from SDK

The Zendrive.registerZendriveCallbackEventListener is provided so that your application can hook into different events sent by Zendrive SDK. If your application fails to run while you are on a trip, data you receive should be stored in a persistent storage, such as async storage.

We recommend the following steps when application receives an event and stores in persistence storage:

1. If the application is running in the foreground, update your UI state and show appropriate messages.

2. For events such as on-accident, you might also want to display a notification if your application is not in foreground UI.

Permissions Module

The react-native-zendrive SDK ships with the permissions module so that your application can easily handle and resolve permission-related issues. This module wraps necessary permissions required by the SDK into simple promise-based method calls.

Resolve Warnings and Errors

When Zendrive SDK notifies an event of kind on-settings-changed on your registered listener, the application should persist the values of the errorsFound and warningsFound flags. These flags should be used as a basis to call the Zendrive.getZendriveSettings method for a list of errors and warnings when application resumes.

See Check for Settings Errors and Warnings.

Teardown Usage

Calling the teardown method makes Zendrive SDK go dormant, which makes it hard for background tracking. When SDK is disabled, the feature to wake it up in the background will also be disabled. It is recommended not to use teardown during component un-mounts or AppState events. The teardown method should be called only when you want to explicitly turn off Zendrive for a user in your application's business logic and not let it be triggered by system events.

Boot Completed Event

The on-boot-completed event is applicable only to Android.

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 registering event listener and handling on-boot-completed.

My Package Replaced Event

Theon-my-package-replaced event is applicable only to Android.

When your app is upgraded on-my-package-replaced is notified on the registered event listener. After an upgrade, your app is no longer running (just like during device restart). So you can handle it in the same way as on-boot-completed. See the example project included in the repository.

Setting Up a Region

Zendrive currently supports two regions, US and EU. You can configure a region during setup process through optional region property in ZendriveConfiguration object.

The following snippet demonstrates how to set up a region.

const resp = await Zendrive.setup({
  driverId: 'your-driver-id',
  sdkKey: 'your-sdk-key',
  region: 'US', // or 'EU'
});

Setting Up Vehicle Type

You need to configure the vehicle type during the setup call to Zendrive.

The following snippet describes how to configure vehicle type.

const resp = await Zendrive.setup({
  driverId: 'your-driver-id',
  sdkKey: 'your-sdk-key',
  attributes: {
    vehicleType: 'car', // or 'motorcycle'
  },
});

Foreground Notification Configuration

This section is applicable only to Android.

Whenever Zendrive SDK detects a trip, it starts a foreground service with a notification. react-native-zendrive provides Notification Settings to configure title, description, icon and notification id. You need to pass this configuration during the setup call to Zendrive.

The following snippet helps you understand how to configure notification content:

const resp = await Zendrive.setup({
  driverId: 'your-driver-id',
  sdkKey: 'your-sdk-key',
  driveDetectionMode: 'auto-on',
  notificationSettings: {
    channelKey: 'Driving',
    inDriveSettings: {
      contentTitle: 'ZD in-drive',
      contentText: 'Driving has started.',
      smallIcon: require('../img/baseline_drive_eta_black_18.png'),
      notificationId: '<id>',
    },
    mayBeInDriveSettings: {
      contentTitle: 'ZD maybe-in-drive',
      contentText: 'May be in drive.',
      smallIcon: require('../img/baseline_drive_eta_black_18.png'),
    },
    waitingForDriveSettings: {
      contentTitle: 'ZD waiting-for-drive',
      contentText: 'Waiting for drive to start.',
      smallIcon: require('../img/baseline_drive_eta_black_18.png'),
      notificationId: '<id>',
    },
  },
});

Android Need-To-Know Items

Further reference related to Android best practices can be found in this guide. Android best practices that can be resolved programmatically via JavaScript are already mentioned on this page.

iOS Need-To-Know Items

Further reference related to iOS best practices can be found in this guide. iOS best practices which can be resolved programmatically via JavaScript are already mentioned on this page.

Frequently Asked Questions

1. Do I need to implement all events notified via registerZendriveCallbackEventListener

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 application permissions are required to use Zendrive SDK?

react-native-zendrive Android module ships with all required permissions in its manifest. It also contains the permissions module to handle various required permissions.

Refer to AndroidManifest to see the permissions used by Zendrive SDK.

Zendrive SDK reports the missing permission as an error via the on-settings-changed event to your registered event listener. See Check for Setting Errors and Warnings for more.

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

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

When the SDK needs to be promoted to the foreground during trip detection phase, it uses the notification settings provided in the setup call. This method is called only on phones running Android Oreo or newer.