Verify API - Push Verify callbacks

The Telesign Verify SDK enables the use of callbacks for verification push notifications to authenticate your users. You get analytics and detailed information about how your users interact with the Push Notifications by using our callback functionality.

While Push Verify callback service unlocks additional valuable information about what happens after the push notification arrives the device of your user, it is optional and Push Verify works well even if you elect to not use its optional callback service.

Key features

• Comprehensive callback events: Through automatic analysis of two primary events—delivery and message read—the SDK internally manages a broader set of events. This reduces development complexity and streamlines integration.
• Flexible integration options: Whether you prefer a manual or an automatic approach, both Android and iOS platforms are supported with clear guidelines and helper classes to ease the integration process.
• Improved analytics and insights: By capturing detailed information about push notification events, the callback service provides valuable analytics that can help refine user engagement strategies and troubleshoot issues more effectively.

Use Push Verify callbacks

📘

NOTE:

Once you have the Verify SDK correctly configured for Push Verify, you have two ways that you can use Push Verify callbacks:

• You can call reportPushStatus in your app where the notification was received or read. (We refer to this as the "manual" way.)
• Alternatively, to facilitate the Push Verify and callback process, we also offer the option to implement an automatic callback functionality. This "automatic" implementation varies in Android and iOS, but the result is the same: the SDK makes the callback for you so you don't need to call the reportPushStatus method.

To use Push Verify callbacks, call the reportPushStatus method to let Telesign know your user has interacted with the push notification. It receives two parameters: data with the push notification information and an event of type PushStatus.

There are just two possible values for the second parameter: delivered and pushClicked.

You might wonder why you can only trigger one of two events if there are actually more than 10 different events reported back to Verify API. The reason is that when you report one of these two events, our SDK internally analyzes the push notification. It automatically triggers additional events so you don’t need to worry about complicated implementations.

Callback events

Code examples

Due to platform restrictions, Android and iOS each have different processes.

Android - manual

You can call the TSVerify.reportPushStatus method in the appropriate place, for example in your FirebaseMessagingService you can use:

override fun onMessageReceived(remoteMessage: RemoteMessage) {
        val jsonString = Json.encodeToString(remoteMessage.data)
        TSVerify.reportPushStatus(data = jsonString, event = DELIVERED)
}

In addition to reporting delivered notifications, you can also notify the SDK when a user taps the push notification. This interaction is referred to as a "Message is read" (402) Event. To report it, use the following method:

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    val jsonString = Json.encodeToString(remoteMessage.data)
    TSVerify.reportPushStatus(data = jsonString, event = PUSH_CLICKED)
}

Android - automatic

If you want the callback functionality to be called automatically, extend the BaseFirebaseMessagingService and implement its abstract onNotificationReceived method:

class AppFirebaseMessagingService : BaseFirebaseMessagingService() {
	override fun onNotificationReceived(remoteMessage: RemoteMessage) {
		// App-specific notification handling. Example: Show a local notification
		showNotification(remoteMessage)
	}
	private fun showNotification(remoteMessage: RemoteMessage) {
		val notificationManager =
		getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
		val notification = NotificationCompat.Builder(this, "default_channel")
			.setContentTitle(remoteMessage.notification?.title)
			.setContentText(remoteMessage.notification?.body)
			.setSmallIcon(R.drawable.ic_notification)
			.build()
		notificationManager.notify(System.currentTimeMillis().toInt(), notification)
	}
}

📘

NOTE:

Automatic callback is only available for Android if you use Firebase, if you have a different push notification provider please use the manual way.

Update your manifest: If you are using Firebase, your app must register its FirebaseMessagingService in the AndroidManifest.xml file.

Kotlin

<service
	android:name=".AppFirebaseMessagingService"
	android:exported="true">
	<intent-filter>
		<action android:name="com.google.firebase.MESSAGING_EVENT" />
	</intent-filter>
</service>

iOS - manual

You can call the TSVerify.reportPushStatus method in the appropriate place, for example in your AppDelegate you can use:

func application(_ application: UIApplication,
                     didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                     fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        TsVerify.shared.reportPushStatus(userInfo: userInfo, event: .delivered)
        // Display and manage your notification here.
        completionHandler(.newData)
     }

In addition to reporting delivered notifications, you can also notify the SDK when a user taps the push notification. This interaction is referred to as a "Message is read" (402) Event. To report it, use the following method:

TsVerify.shared.reportPushStatus(userInfo: userInfo, event: .pushClicked)

iOS - automatic

Telesign Verify API SDK can help you with the display of your notification by using the helper class TsNotificationManager. This class allows you to report the events and display your local notifications.

1. In your AppDelegate, configure the TSNotificationManager class:

   Swift

   func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        application.registerForRemoteNotifications()
        configureFirebase()
        let center = UNUserNotificationCenter.current()
        center.delegate = TsNotificationManager.shared
        TsNotificationManager.shared.delegate = self
        return true
    }
   

2. Then in your application: didReceiveRemoteNotification method you can use the TsNotificationManager.shared.showNotification convenience method. It will show a local notification and report the event.
   
   

   Swift

      func application(_ application: UIApplication,
                        didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                        fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
           TsNotificationManager.shared.showNotification(userInfo: userInfo, title: "My Company", bodyText: "Verification Attempt")
           navigateToPushVerificationChallenge = true
           verifyRepository.savePushData(pushData: userInfo)
           completionHandler(.newData)
        }
   

You can receive notifications of tapped events. These events occur when a user has tapped on a notification from you. If you set TsNotificationManager.shared as the UNUserNotificationCenter delegate and set a delegate for TsNotificationManager.shared.delegate = self, then you don’t need to do any additional step to report the tapping of a push notification.

In this case, remember that you can handle the tapping of the notification with the func notificationTapped(notification: UNNotificationResponse) method of your delegate.