Skip to main content

Push notifications

About this documentation

This documentation only describes how to configure the SDK for our push notifications feature. If you want to learn about the feature and the full set of implementation requirements, see the main feature documentation:


 

How do push notifications work?​

For Android, we support the use of Firebase Cloud Messaging (FCM) push notifications to notify the end-user when an operation has started.

Want to learn more?

To learn more about how FCM works, see the Firebase Cloud Messaging page in the Android developer documentation.

Configure the SDK​

Prerequisites​

Before you start, you need make sure that you have set up support for FCM push notifications. This documentation assumes that the following steps have been completed:

  1. Add Firebase to your Android project.
  2. Set up a Firebase Cloud Messaging client on Android
  3. Ensure that:
    • FcmMessagingService extends FirebaseMessagingService.
    • You have added the required entries for FCM to AndroidManifest, as described in the FCM documentation.

1. Add new service entry to AndroidManifest.xml​

Verify that you have added a new service entry on your AndroidManifest.xml file.

Example: Add new service entry to AndroidManifext.xml
<service
    android:name="com.encapsecurity.android.standardapp.fcm.FcmMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>

2. FcmMessagingService​

Set push token on the Encap controller​

  1. When FCM invokes the onNewToken(newToken: String) method of FirebaseMessagingService, the service should set the new push token on the EncapController.
    Example: Set push token on Encap controller
    override fun onNewToken(newToken: String) {
        super.onNewToken(newToken)

        controller.config = EncapConfig.Builder(controller.config)
            .setPushToken(newToken)
            .build()
    }
  2. The onNewToken() method is called when a token is first generated and again if the token changes. This happens when:
    • The app is restored on a new device.
    • The end-user uninstalls/reinstalls the app.
    • The end-user clears app data.

Receiving messages​

When FCM invokes the onMessageReceived(remoteMessage: RemoteMessage) of the FcmMessagingService:

  • Create an intent with the action com.google.firebase.MESSAGING_EVENT.
  • Set the intent's extra data with remoteMessage.toIntent().
  • Send the intent to the Activity, either directly or via a notification with a PendingIntent() if the app is in the background.
override fun onMessageReceived(remoteMessage: RemoteMessage) {
    val intent = Intent(this, MainActivity::class.java).apply {
        action = "com.google.firebase.MESSAGING_EVENT"
        putExtras(remoteMessage.toIntent())
    }
    // If application is in foreground, immediately send intent to activity
    // Otherwise, display a notification instead
    if(appInForeground){
        startActivity(intent)
    } else {
        displayNotification(intent)
    }
}

3. Activity​

  1. When the Activity receives an intent in onNewIntent(Intent) or onCreate(), you should examine the intent.
  2. If the intent is an FCM intent with action com.google.firebase.MESSAGING_EVENT, then:
    • Create a push message of it using PushMessageFactory.createFromIntent(Intent).
    • If the push message is a start message, then examine whether it starts an activation or authentication, and call the Encap API's corresponding start method.
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        processIntent(intent)
    }

    private fun processIntent(intent: Intent) {
        try {
            if ("com.google.firebase.MESSAGING_EVENT" == intent.action) {
                // Launched from FCM.
                processPushMessage(intent)
            } else {
                // Your other notifications handling
            }
        } catch (ex: Exception) {
            Log.d(TAG, "processIntent: caught exception: ", ex)
        }
    }

    private fun processPushMessage(intent: Intent) {
        val pushMessage = PushMessageFactory.createFromIntent(intent)

        if (pushMessage.isStartMessage) {
            if (pushMessage.isActivationMessage) {
                // Handle activation
            } else if (pushMessage.isAuthenticationMessage) {
                // Handle authentication
            } else if(pushMessage.isRecoveryPerformedNotification) {
                // Handle recovery performed
            }
            else {
                Log.d(TAG, "unexpected message type")
            }
        }
    }
Detailed implementation

For more details on the implementation, see the com.encapsecurity.encap.example.android.testapp.util.FcmMessagingService class.

Custom push payload​

You can send a custom payload in the push to the device.

If the custom payload is sent, it can be read by creating a PushMessage with PushMessageFactory.createFromIntent() either:

  • In the FcmMessagingService class within onMessageReceived().
  • In in the Activity within onNewIntent().
val pushMessage = PushMessageFactory.createFromIntent(intent)
val payload: String? = pushMessage.customPayload
On this page