Overview

On incoming events such as a new message, or an incoming call, the user often expects to receive a push notification or the app itself. If the app is not active (is in the background), push notifications are the only way to notify app about new events.

This guide explains how to configure your Android app to receive push notifications from the Client SDK.

Set up Firebase project for your Android application

In order to enable push notifications for your Android application, you need to configure your Android application, create a new Firebase project and connect it to your Vonage API application.

Configure Android project

Let's start with setting up Android project.

To add the Client SDK dependency

Add Client SDK to your project.

Add Firebase Cloud Messaging dependency

In your IDE, in your app level build.gradle file (usually app/build.gradle), add the firebase-messaging dependency:

Kotlin

Groovy

dependencies{
    implementation("com.google.firebase:firebase-messaging:20.3.0")
}

dependencies{
    implementation 'com.google.firebase:firebase-messaging:20.3.0'
}

Implement a custom service class to receive push notifications

If you do not have one already, create a class (service) that extends FirebaseMessagingService.

In order for Vonage API application to be able to send push notifications to a device, the Vonage server has to know the device token, also known as InstanceID.

In your class that extends FirebaseMessagingService, override onNewToken() method and update the NexmoClient by passing new token:

Kotlin

Java

class MyFirebaseMessagingService: FirebaseMessagingService() {

    // We can retrieve client instance only if it has been already initialized
    // NexmoClient.Builder().build(context)
    private val client = NexmoClient.get()

    override fun onNewToken(token: String) {
        super.onNewToken(token)

        client.enablePushNotifications(token, object: NexmoRequestListener<Void> {
            override fun onSuccess(p0: Void?) { }

            override fun onError(apiError: NexmoApiError) {}
        })
    }
}

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    // We can retrieve client instance only if it has been already initialized
    // new NexmoClient.Builder().build(context)
    private NexmoClient client = NexmoClient.get();

    @Override
    public void onNewToken(@NonNull String token) {
        super.onNewToken(token);

        client.enablePushNotifications(token, new NexmoRequestListener<Void>() {
            @Override
            public void onSuccess(@Nullable Void p0) {}

            @Override
            public void onError(@NonNull NexmoApiError nexmoApiError) {}
        });
    }
}

Make sure your service is declared in your AndroidManifest.xml (typically app/src/main/AndroidManifest.xml) by adding service tag inside application tag:

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

Receive push notifications

Push notifications are received in your implementation of MyFirebaseMessagingService, on onMessageReceived() method.

You can use NexmoClient.isNexmoPushNotification(message.data)) to determine if the message is sent from Vonage server.

Use processPushNotification(message.data, listener) to process the data received from Firebase Cloud Messaging (FCM) into an easy to use Nexmo object:

Kotlin

Java

class MyFirebaseMessagingService : FirebaseMessagingService() {

    // We can retrieve client instance only if it has been already initialized
    // NexmoClient.Builder().build(context)
    private val client = NexmoClient.get()

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        //...   
    }

    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        // determine if the message is sent from Nexmo server
        if (NexmoClient.isNexmoPushNotification(remoteMessage.data)) {
            client.processNexmoPush(remoteMessage.data, object : NexmoPushEventListener {
                override fun onIncomingCall(call: NexmoCall?) {
                    Log.d("TAG", "FirebaseMessage:onIncomingCall() with: $call")
                }

                override fun onNewEvent(event: NexmoEvent?) {
                    Log.d("TAG", "FirebaseMessage:onNewEvent() with: $event")
                }

                override fun onError(apiError: NexmoApiError?) {
                    Log.d("TAG", "FirebaseMessage:onError() with: $apiError")
                }
            })
        }
    }
}

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    // We can retrieve client instance only if it has been already initialized
    // new NexmoClient.Builder().build(context)
    private NexmoClient client = NexmoClient.get();

    @Override
    public void onNewToken(@NonNull String token) {
        super.onNewToken(token);

        //...
    }

    @Override
    public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
        super.onMessageReceived(remoteMessage);

        // determine if the message is sent from Nexmo server
        if (NexmoClient.isNexmoPushNotification(remoteMessage.getData())) {
            client.processNexmoPush(remoteMessage.getData(), new NexmoPushEventListener() {
                @Override
                public void onIncomingCall(NexmoCall call) {
                    Log.d("TAG", "FirebaseMessage:onIncomingCall() with: " + call);
                }

                @Override
                public void onNewEvent(NexmoEvent event) {
                    Log.d("TAG", "FirebaseMessage:onNewEvent() with: " + event);
                }

                @Override
                public void onError(NexmoApiError apiError) {
                    Log.d("TAG", "FirebaseMessage:onError() with: " + apiError);
                }
            });
        }
    }
}

Connect Vonage API application to Firebase

To connect Vonage API Application with Firebase you will need the following:

1. Vonage API Application id
2. Vonage developer JWT
3. Firebase project id
4. Firebase token

Get Vonage application Id

Obtain your VONAGE_APP_ID. You can access existing application in the Nexmo Dashboard. If you don't have an application already you can create the new application via Nexmo CLI.

Generate a Vonage developer JWT

JWTs are used to authenticate a user into the Client SDK.

To generate a VONAGE_DEV_JWT run the following command. Remember to replace the VONAGE_APP_ID with id of your Vonage application:

nexmo jwt:generate ./private.key exp=$(($(date +%s)+86400)) acl='{"paths":{"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{}}}' application_id=VONAGE_APP_ID

Get Firebase project Id

Get your FIREBASE_PROJECT_ID from the Firebase console. Navigate to Firebase console -> Project settings -> General.

Get Firebase token

Get your FIREBASE_TOKEN from the Firebase console. Navigate to Firebase console -> Project settings -> Service accounts and generate a new private key.

Link the Nexmo backend push service with the Firebase application

To link the Nexmo backend push service with the Firebase application you need to make a single request.

Fill VONAGE_APP_ID, VONAGE_DEV_JWT, FIREBASE_PROJECT_ID and FIREBASE_TOKEN with previously obtained values and run the below command:

VONAGE_APP_ID=
VONAGE_DEV_JWT=
FIREBASE_PROJECT_ID=
FIREBASE_TOKEN=

curl -v -X PUT \
   -H "Authorization: Bearer $VONAGE_DEV_JWT" \
   -H "Content-Type: application/json" \
   -d "{\"token\":\"$FIREBASE_TOKEN\", \"projectId\":\"$FIREBASE_PROJECT_ID\"}" \
   https://api.nexmo.com/v1/applications/$VONAGE_APP_ID/push_tokens/android  

Putting it all together

Now you can test your push notification setup by calling any user. Incoming call will trigger onIncomingCall callback presented above.

Conclusion

In this guide you have seen how to set up push notifications.