Integrate with Zendrive Webhooks

The same endpoint that is used for the Engagement Webhook and the Push Notification services will be used for all types of engagement triggers. Therefore, in order to determine the nature of engagement, you will need to parse the metadata received along with the engagement webhook payload.

This section includes the following topics:

1.0. Permission Error Alert Notification

We recommend that you use local mechanisms to alert the user whenever there are permission issues affecting trip detection. To accomplish this, we employ background fetch and processing to wake the application up and check for any permission errors. If any errors exist, we send a local notification to prompt the user to fix the issue. For more information, refer to the implementation guidelines provided here.

Note that permission alerts are more timely if presented as a local notification on Zendrive SDK callbacks, as detailed here. You can use the webhook to trigger any other type of communication, such as, text or email.

2.0. First Trip Completion Notification

This webhook is sent for users who just took their first trip. You can identify type of notification by passing the metadata field to the can_handle_webhook method mentioned in the following code snippet:

class FirstTripWebhookHandler(AbstractEngagementWebhookHandler):
   def __init__(self, data):
       if not self.can_handle_webhook(data):
           raise EngagementService.IncorrectHandlerError()
       super().__init__(data)

   @staticmethod
   def can_handle_webhook(data):
       type = data["type"]
       subtype = data["subtype"]
       return type == 'milestone_based' and subtype == 'trip-1'

   def get_push_payload(self):
       push_payload = super().get_push_payload()
       push_payload["message"] = {
           "title":
           "Congratulations on your 1st trip",
           "body":
           "Continue driving to increase your chances of being qualified for an offer."
       }
       return push_payload

3.0. Trips Reminder Notification

This webhook is received for users who have not taken a trip for the duration specified in the inactivity_days field as per the Inactivity Webhook configuration. You can identify the Trips Reminder Notification by parsing the metadata field to the can_handle_webhook indicated in the following code snippet:

class InactivityWebhookHandler(AbstractEngagementWebhookHandler):
   def __init__(self, data):
       if not self.can_handle_webhook(data):
           raise EngagementService.IncorrectHandlerError()
       super().__init__(data)

   @staticmethod
   def can_handle_webhook(data):
       type = data["type"]
       subtype = data["subtype"]
       return type == 'activity_based' and subtype == 'inactivity'

   def get_push_payload(self):
       push_payload = super().get_push_payload()
       try:
           last_drive_date = datetime.strptime(
               self.webhook.metadata.date_last_drive, "%Y-%m-%d").date()
           today = datetime.today().date()
           days_since_last_drive = (today - last_drive_date).days
           body_text = "You have not taken any trips in the last {} days. Keep taking trips more often to unlock " \
                       "your personalized discount.".format(days_since_last_drive)
       except (AttributeError, TypeError):
           body_text = "You haven't taken your first trip yet. Start driving to see your score."
       push_payload["message"] = {"title": "We miss you!", "body": body_text}
       return push_payload

4.0. Program Milestone Notification

This webhook is received for users who have completed a milestone in the IQL program. It is sent for each of the days_list configured for the Opt-in Days type of engagement webhook. You can identify this type of notification by passing the metadata field received in the engagement webhook to the can_handle_webhook method mentioned in the following code snippet:bj

class OptInDaysWebhookHandler(AbstractEngagementWebhookHandler):
   def __init__(self, data):
       if not self.can_handle_webhook(data):
           raise EngagementService.IncorrectHandlerError()
       super().__init__(data)

   @staticmethod
   def can_handle_webhook(data):
       type = data["type"]
       subtype = data["subtype"]
       return type == 'milestone_based' and subtype == 'opt_in_days'

   def get_push_payload(self):
       push_payload = super().get_push_payload()
       try:
           opt_in_days = self.webhook.metadata.opt_in_days
           distance_miles = self.webhook.metadata.distance_miles
           body_text = "You've been enrolled for {} days, and you've driven {} miles. You're making great progress " \
                       "towards your exclusive discount.. See your detailed ratings and trips in the app.".format(
               int(opt_in_days), int(distance_miles))
       except (AttributeError, TypeError):
           body_text = "You're making great progress towards your exclusive discount.. See your detailed ratings and " \
                       "trips in the app. "
       push_payload["message"] = {
           "title": "You're making good progress!",
           "body": body_text
       }
       return push_payload

5.0. Offer Click Reminder Notification

This webhook is received for users who have not acted on the offer made to them. It will be called on each of the days indicated in the days_list configuration enabled for this type of webhook. You can identify this type of webhook by parsing the metadata field to the can_handle_webhook method mentioned in the following code snippet:

class NoClickWebhookHandler(AbstractEngagementWebhookHandler):
   def __init__(self, data):
       if not self.can_handle_webhook(data):
           raise EngagementService.IncorrectHandlerError()
       super().__init__(data)

   @staticmethod
   def can_handle_webhook(data):
       type = data["type"]
       subtype = data["subtype"]
       return type == 'activity_based' and subtype == 'no_click'

   def get_push_payload(self):
       push_payload = super().get_push_payload()
       push_payload["message"] = {
           "title":
           "Your personalised discount offer is ready!",
           "body":
           "It's been few days since you received your personalised discount offer, take advantage of it "
           "before it's too late. "
       }
       return push_payload

6.0. Android - Engagement Webhook notifications

IQL sends out push notifications to users to deliver important notification messages. The IQL reference application supports the following engagement notifications:

Trips Reminder Notification
Offer Click Reminder Notification
First Trip Completion Notification
Program Milestone Notification

Firebase Cloud Management services SDK can be used to receive push notifications. The IQL reference application receives the notification payload via the FirebaseMessagingService.

class MessagingServices : IqlFirebaseServices() {

   private val dispatcher: NotificationDispatcher by lazy {
       NotificationDispatcherImpl(applicationContext)
   }

   override fun onMessageReceived(message: RemoteMessage) {
       super.onMessageReceived(message)
       Timber.d("Iql Push notification message: ${message.data}")
       Timber.d("Iql Push notification message notification title : ${message.notification?.title}")
       Timber.d("Iql Push notification message notification body: ${message.notification?.body}")
       try {
           val data = NotificationDataModel.getSerializeData(message.data)
           val notification =
               NotificationMessageModel(message.notification?.title, message.notification?.body)
           dispatcher.dispatch(data, notification)
       } catch (ex: SerializationException) {
           Timber.d(ex)
       }
   }
}


interface NotificationDispatcher {
   fun dispatch(data: NotificationDataModel, notification: NotificationMessageModel)
}

internal class NotificationDispatcherImpl(val context: Context) : NotificationDispatcher {

   companion object {
       const val ACTIVITY_BASED_NOTIFICATION_ID = 1007
       const val MILE_STONE_BASED_NOTIFICATION_ID = 1008
   }

   override fun dispatch(data: NotificationDataModel, notification: NotificationMessageModel) {
       when (data.type) {
           NotificationType.ACTIVITY_BASED -> {
               // activity based notification type
               when (data.subtype) {
                   NotificationSubType.INACTIVITY, NotificationSubType.NO_CLICK -> {
                       // inactivity based notification sub type or
                       // no click on offer
                       showNotification(context, ACTIVITY_BASED_NOTIFICATION_ID, notification)
                   }
                   else -> {
                       Timber.d("data.subtype is ${data.subtype} when ACTIVITY_BASED notification")
                   }
               }
           }
           NotificationType.MILESTONE_BASED -> {
               // milestone based notification type
               when (data.subtype) {
                   NotificationSubType.FIRST_TRIP, NotificationSubType.OPT_IN_DAYS -> {
                       // first trip done OR
                       // the opt in days webhook after user completes X number of days in program
                       showNotification(context, MILE_STONE_BASED_NOTIFICATION_ID, notification)
                   }
                   else -> {
                       Timber.d("data.subtype is ${data.subtype} when MILESTONE_BASED notification")
                   }
               }
           }
           NotificationType.HEARTBEAT -> {
               (context.applicationContext as MainApplication).initZendriveSDK()
           }
           else -> {
               Timber.d("notification type is ${data.type}")
           }
       }
   }

   private fun showNotification(
       context: Context,
       notificationId: Int,
       notification: NotificationMessageModel
   ) {
       Timber.d("notification title: ${notification.title}")
       Timber.d("notification body: ${notification.body}")
       NotificationProvider.showNotification(
           context,
           notificationId = notificationId,
           title = notification.title ?: "",
           text = notification.body ?: "",
           Intent(context, HomeActivity::class.java)
       )
   }
}

7.0. IQL Reference Application UX Design

Here is the overall design implementation for the IQL Reference Application:

PreviousEnable Zendrive Webhooks NextIntegrate IQL with iOS