Enable Zendrive Webhooks

This section describes how to enable Engagement Webhook with the IQL platform, and includes the following topics:

1.0. Create Endpoint of Engagement

Create a new endpoint in your backend that will be configured as an engagement webhook with Zendrive’s IQL platform. The IQL platform will call this endpoint to allow you to engage with your users via SMS, email, push notifications and so on. In this section, you will learn how to create an engagement endpoint for push notifications.

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

2.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 day configured in the days_list configuration. You can identify this notification type by passing the metadata field received in the engagement webhook to the can_handle_webhook method indicated 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

3.0. First Trip Completion Notification

This webhook is for users who just took their first trip. You can determine this type of notification by passing the metadata field received in the engagement webhook to the can_handle_webhook method indicated 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

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 days within the days_list configured for the Opt-In days type of engagement webhook. You can determine 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:

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. Alert Notification

The IQL application requires a few mandatory permissions in order to record trips and driving events seamlessly. These permissions include Location, Activity recognition permission, GPS and so on.

We recommend that you use application mechanisms to alert the user whenever there are permission issues that affect trip detection. The application checks for these permissions every 6 hours. If the permissions are not given or have been revoked at any point, the application throw up a notification to the user. The notification, when tapped, will display a permission error band with which with a Click to Action button to allow the required permission.

The application also displays permission error notifications in response to configuration changes. In such cases, the application gets a callback, and displays the notification to the user. The application checks for missing permissions locally, instead of depending on permission error push notifications, in order to avoid delays. The application can also use the permission webhook to remind user to resolve the missing permission issue

6.0. Android - Engagement webhook notifications

IQL can send push notifications to users. It supports the following engagement notifications:

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

You can use the Firebase Cloud Messaging (FCM) SDK to receive push notifications. The IQL application receives the notification payload using 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)
       )
   }
}

PreviousUser Engagement Optimization NextIntegrate with Zendrive Webhooks