Setting up push notifications

Push notifications

The Zendesk SDK for Android supports Firebase Cloud Messaging (FCM) for sending and receiving push notifications. The following steps will guide you through the process of setting up push notifications for the Zendesk SDK in your app.

FCM is included as a compile-only dependency of the SDK. If you don't plan on using push notifications, no additional steps are required.

If you plan to use push notifications, add the dependencies below to your gradle file and implement cloud messaging in your app as described in Set up a Firebase Cloud Messaging client app on Android in the Firebase docs so your app is capable of receiving push notifications from Firebase.

implementation platform("com.google.firebase:firebase-bom:{latest_version}")
implementation "com.google.firebase:firebase-messaging:{latest_version}"

---

Step 1 - Setting up Firebase

If you have not already done so, open the Firebase console and create a new project. From the Project settings window, copy and store your Firebase key and ID in a secure location, and download google-services.json.

---

Step 2 - Adding your Firebase key and ID in the Zendesk Admin Center

Enter your Firebase key and ID into the Zendesk Admin Center. See Working with messaging for your mobile channel. If you are not an admin, please contact the admin on your account to assist you with this step.

---

Step 3 - Configuring your Android project

Copy the google-services.json file to your Android Studio project's app folder. After adding the file, Android Studio will automatically sync your project with the gradle files. If it doesn't, you can trigger a sync manually by clicking Sync Project with Gradle Files.

Note: Each Firebase project corresponds to a unique google-services.json file. If you change Firebase projects, make sure to swap this file with the one from the new Firebase console.

---

Step 4 - Implementing push notifications in your app's codebase

Updating push notification tokens (Firebase v2 compatible)

With FCM v2, you should use the new async API to retrieve the registration token. You must notify the SDK when a new token has been created or refreshed.

Kotlin

import com.google.firebase.messaging.FirebaseMessaging
import zendesk.messaging.android.push.PushNotifications

// Retrieve the current FCM registration token (Firebase v2)
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val token = task.result
        PushNotifications.updatePushNotificationToken(token)
    }
}

// Or in your FirebaseMessagingService:
override fun onNewToken(newToken: String) {
    PushNotifications.updatePushNotificationToken(newToken)
}

Java

import com.google.firebase.messaging.FirebaseMessaging;
import zendesk.messaging.android.push.PushNotifications;

// Retrieve the current FCM registration token (Firebase v2)
FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(task -> {
        if (task.isSuccessful()) {
            String token = task.getResult();
            PushNotifications.updatePushNotificationToken(token);
        }
    });

// Or in your FirebaseMessagingService:
@Override
public void onNewToken(@NonNull String newToken) {
    PushNotifications.updatePushNotificationToken(newToken);
}

Note: It is recommended to proactively fetch the token using getToken() after app install or token refresh, as well as handling onNewToken.

---

Using the default implementation of FirebaseMessagingService

The Zendesk SDK for Android provides a default implementation of FirebaseMessagingService that will:

• Notify the SDK when a new device token has been created
• Display the push notification if Messaging was the source of the received message

If the Zendesk SDK for Android is the only expected source of push notifications for your app, register the DefaultMessagingService class in the application tag of your AndroidManifest.xml:

<application>
    <!-- Use the SDK default messaging service -->
    <service android:name="zendesk.messaging.android.push.DefaultMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
</application>

---

Using a custom implementation of FirebaseMessagingService

If you want to use your own FirebaseMessagingService implementation, the Zendesk SDK provides convenience methods for handling push notifications.

Displaying a push notification from Messaging

When a push notification is received, you must determine if it belongs to the SDK. You can then give the data to the SDK to display the notification on your behalf.

Kotlin

import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import zendesk.messaging.android.push.PushNotifications
import zendesk.messaging.android.push.PushResponsibility.*

class SampleMessagingService : FirebaseMessagingService() {
    override fun onMessageReceived(remoteMessage: RemoteMessage) {
        val responsibility = PushNotifications.shouldBeDisplayed(remoteMessage.data)
        when (responsibility) {
            MESSAGING_SHOULD_DISPLAY -> {
                // This push belongs to Messaging and the SDK is able to display it to the end user
                PushNotifications.displayNotification(context = this, messageData = remoteMessage.data)
            }
            MESSAGING_SHOULD_NOT_DISPLAY -> {
                // This push belongs to Messaging but it should not be displayed to the end user
            }
            NOT_FROM_MESSAGING -> {
                // This push does not belong to Messaging
            }
        }
    }
}

Java

import androidx.annotation.NonNull;
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import zendesk.messaging.android.push.PushNotifications;
import zendesk.messaging.android.push.PushResponsibility;
public class SampleMessagingService extends FirebaseMessagingService {
	@Override
	public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
		PushResponsibility responsibility = PushNotifications.shouldBeDisplayed(remoteMessage.getData());
		switch (responsibility) {
			case MESSAGING_SHOULD_DISPLAY:
            	// This push belongs to Messaging and the SDK is able to display it to the end user
                PushNotifications.displayNotification(this, remoteMessage.getData());
                break;
            case MESSAGING_SHOULD_NOT_DISPLAY:
            	// This push belongs to Messaging but it should not be displayed to the end user
            	break;
            case NOT_FROM_MESSAGING:
                // This push does not belong to Messaging
                break;
		}
	}
}

Note: When the app is in a background state, PushNotifications.displayNotification will bring you back to the conversation.
When the app is in a killed state, it will just open the app as the SDK is not initialized then.
If you call this method with a notification that is not from Zendesk, it won't be displayed.

If you want to change that behaviour, you will have to implement your own handling of the push display as well as handling the initialization of the SDK and call .showMessaging to display the conversation.

---

(Optional) Step 5 - Changing the notification small icon

The Zendesk SDK for Android uses a chat bubble icon when displaying notifications from Messaging. This icon can be customized by providing a resource ID to your own icon.

Kotlin

PushNotifications.setNotificationSmallIconId(R.drawable.my_icon)

Java

PushNotifications.setNotificationSmallIconId(R.drawable.my_icon);

---

Demo App

You can find a demo app showcasing this feature in our Zendesk SDK Demo app github.

---

Additional Resources

• Firebase Cloud Messaging documentation