Rich push notifications

With rich push, you can do more than just send a simple notification; you can send an image, open a deep link when someone taps your message, and more!

 Our mobile SDKs are in alpha and subject to change

While we’re very excited about our mobile SDKs, they’re still works in progress! If you want to try them out, contact

This page is part of an introductory series to help you get started with the essential features of our SDK. The highlighted step(s) below are covered on this page. Before you continue, make sure you've implemented previous features—i.e. you can't identify people before you initialize the SDK!

graph LR getting-started(Install SDK) -->B(Initialize SDK) B --> identify(identify people) identify -.-> track-events(Send events) identify -.-> push(Receive push) identify -.-> rich-push(Receive Rich Push) track-events --> testing-error-handling(handle errors) push --> testing-error-handling rich-push --> testing-error-handling click getting-started href "/docs/sdk/android/getting-started" click B href "/docs/sdk/android/getting-started/#initialize-the-sdk" click identify href "/docs/sdk/android/identify" click track-events href "/docs/sdk/android/track-events/" click push href "/docs/sdk/android/push" click rich-push href "/docs/sdk/android/rich-push" click testing-error-handling href "/docs/sdk/android/testing-error-handling" style rich-push fill:#B5FFEF,stroke:#007069

Set up rich push

Rich push is included with the messaging-push-fcm SDK. For now, our rich push feature only supports images and deep links. We’ll add additional features here as we continue to develop our SDKs.

Send a rich push

To send a rich push through, you need to use our Custom Payload editor, which takes a JSON structure. In the editor, you’ll select the type of device you want to send your message to: you can have separate payloads for Android and iOS. In our case, you’ll click Android.

The custom payload editor for a push notification
The custom payload editor for a push notification

The following example shows a rich push with an image and a link. See the Deep links section below for help enabling deep links in your app.

  "message": {
    "data": {
      "link": "remote-habits://deep?message=hello&message2=world",
      "image": "",
      "title": "Hi there",
      "body": "How're you doing?"

Deep links provide a way to link to a screen in your app. There are two ways to set up deep links. If you use both methods, the CustomerIOUrlHandler takes precedence.

  • Using intent filters in your AndroidManifest.xml file.

    Click here to learn more about intent filters.

    <intent-filter android:label="deep_linking_filter">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "remote-habits://deep” -->
            android:scheme="remote-habits" />
  • Using CustomerIOUrlHandler—a URL handler feature provided by the SDK. When configuring your CustomerIO instance, attach a listener using the setCustomerIOUrlHandler method of CustomerIO.Builder. You should do this in the entry point of the application, which is usually the Application class.
class MainApplication : Application(), CustomerIOUrlHandler {

    override fun onCreate() {
        val builder = CustomerIO.Builder(
            siteId = "YOUR-SITE-ID",
            apiKey = "YOUR-API-KEY",
            appContext = this
    override fun handleCustomerIOUrl(uri: Uri): Boolean {
        // return true if you plan to handle the deep link yourself 
        // return false if you want CustomerIO SDK to do it for you
        TODO("Pass the link to your Deep link managers")
When someone taps a push notification with a deep link, the SDK calls the urlHandler specified in your CustomerIO.Builder object first. If the handler is not set or returns false, the SDK will open the link in a browser.

Test Rich Push

After you set up rich push, you should test your implementation. Use the payloads below to send a push in the web app with a Custom Payload.

In both of the test payloads below, you should:

  • Set the link to the deep link URL that you want to open when your tester taps your notification.
  • Set the image to the URL of an image you want to show in your notification. It’s important that the image URL starts with https:// and not http:// or the image might not show up.
Copied to clipboard!