Best Practices and F.A.Q

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

Zendrive module promises

React native bridge is asynchronous by design. All the methods that bridge to native sdk are returned as promises. Its highly recommended that these promises are resolved properly and all cases are handled. There are two ways to handle these

Chaining with then, catch and finally

Lets take example of setup method which 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
  });

Using async/await

Lets take the same example as above. With 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
}

You can follow any of these methods or a combination of these two ways across your application.

Handling events from SDK

Zendrive.registerZendriveCallbackEventListener is provided so that your application can hook into different events sent by Zendrive SDK. During a trip it is possible that your UI application process isn't running. So it is imperative that the data you receive during these events are stored in some kind of persistence, possibly async storage.

Here are the steps we recommend

  1. Application receives the event and stores in persistence.
  2. If application is running in foreground, update your UI state if need be and show appropriate messages in your UI.
  3. For some events like on-accident, you might also want display a notification to user if your app is not in foreground UI.

Permissions module

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

Refer to this guide for complete reference.

Resolve warnings and errors

When the 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 Zendrive.getZendriveSettings to get a list of errors and warnings on app resume.

See Check for Settings Errors and Warnings.

Teardown usage

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. It is recommended not to use teardown during component unmounts or AppState events. 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.

Boot completed event

Note: on-boot-completed event is applicable only to android

Whenever a phone dies and restarts, your app is no longer running unless the user explicitly starts it. You can start your app automatically by registering event listener and handling on-boot-completed.

My package replaced event

Note: on-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.

See the following snippet demonstrating setting 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 configure the vehicle type during the setup call to Zendrive

See the following snippet to understand how to configure vehicle type

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

See ZendriveConfiguration for further reference.

Foreground notification configuration

Note: this section is applicable only to android

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

See the following snippet to 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>',
    },
  },
});

See ZendriveConfiguration for further reference.

Android need-to-knows

Further reference related to android best practices can be found in this guide. Those which can be resolved programmatically via js are already mentioned in this page.

iOS need-to-knows

Further reference related to ios best practices can be found in this guide. Those which can be resolved programmatically via js are already mentioned in this page.

Frequently Asked Questions

Q. 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.

Q. What app permissions are required to use the Zendrive SDK?

react-native-zendrive android module ships with all required permissions in its manifest. It also permissions module to handle various permissions it requires.

Refer AndroidManifest to see the permissions used by the SDK.

The 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.

Q. 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 uses the notification settings provided in the setup call. This method is called only on phones running Android Oreo or newer.