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!

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 --> test-support(Handle errors) push --> test-support rich-push --> test-support 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 test-support href "/docs/sdk/android/test-support" 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 Customer.io, 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": {
    "notification": {
      "image": "https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Fpawsindoorssouthend.com%2Fwp-content%2Fuploads%2F2020%2F04%2Ftips-for-choosing-doggy-day-care.jpg",
      "title": "Hi there",
      "body": "How're you doing?"
    },
    "data": {
      "link": "remote-habits://deep?message=hello&message2=world"
    }
  }
}
        • body_loc_arg string
          Variable string values used in place of the format specifiers in body_loc_key to localize the body text to the user’s current localization. See Formatting and Styling for more information.
        • body_loc_key string
          The key to the body string in the app’s string resources that you want to use to localize the body text to the user’s current localization. See String Resources for more information.
        • click_action string
          The action that occurs when user taps on the notification. Launches an activity with a matching intent filter when a person taps the notification.
        • color string
          The notification’s icon color, in #rrggbb format.
        • icon string
          Sets the notification icon to myicon for drawable resource myicon. If you don’t send this key, FCM displays the launcher icon from your app manifest.
        • sound string
          The sound that plays when the device receives the notification. Supports "default" or the filename of a sound resource bundled in your app. Sound files must reside in /res/raw/.
        • tag string

          Identifier to replace existing notifications in the notification drawer. If empty, each request creates a new notification.

          If you specify a tag, and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification drawer.

        • title_loc_arg string
          Variable string values used in place of the format specifiers in title_loc_key to localize the title text to the user’s current localization. See Formatting and Styling for more information.
        • title_loc_key string
          The key to the title string in the app’s string resources that you want to use to localize the title text to the user’s current localization. See String Resources for more information.
      • link string
        A deep link (to a page in your app), or a link to a web page.
      • body string
        The body of your push notification.
      • image string
        The URL of an HTTPS image that you want to use for your message.
      • title string
        The title of your push notification.

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” -->
        <data
            android:host="deep"
            android:scheme="remote-habits" />
    </intent-filter>

  • 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() {
        super.onCreate()
        val builder = CustomerIO.Builder(
            siteId = "YOUR-SITE-ID",
            apiKey = "YOUR-API-KEY",
            appContext = this
        )
        builder.setCustomerIOUrlHandler(this)
        builder.build()
    }
    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 Customer.io 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.

Rich Push Payloads

To send a rich push in Customer.io, 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 part of your payload interpreted by the Android SDK is contained in the message.data object. This object can contain other custom data for your app, but you’ll need to do additional development to support keys beyond title, body, link, and image—all of which are handled by the SDK.

{
  "message": {
    "notification": {
      "title": "string", //(optional) The title of the notification.
      "body": "string", //The message you want to send.
      "image": "string" //https URL to an image you want to include in the notification
    },
    "data": {
      "link": "string", //Deep link in the format remote-habits://deep?message=hello&message2=world
    }
  }
}
        • body_loc_arg string
          Variable string values used in place of the format specifiers in body_loc_key to localize the body text to the user’s current localization. See Formatting and Styling for more information.
        • body_loc_key string
          The key to the body string in the app’s string resources that you want to use to localize the body text to the user’s current localization. See String Resources for more information.
        • click_action string
          The action that occurs when user taps on the notification. Launches an activity with a matching intent filter when a person taps the notification.
        • color string
          The notification’s icon color, in #rrggbb format.
        • icon string
          Sets the notification icon to myicon for drawable resource myicon. If you don’t send this key, FCM displays the launcher icon from your app manifest.
        • sound string
          The sound that plays when the device receives the notification. Supports "default" or the filename of a sound resource bundled in your app. Sound files must reside in /res/raw/.
        • tag string

          Identifier to replace existing notifications in the notification drawer. If empty, each request creates a new notification.

          If you specify a tag, and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification drawer.

        • title_loc_arg string
          Variable string values used in place of the format specifiers in title_loc_key to localize the title text to the user’s current localization. See Formatting and Styling for more information.
        • title_loc_key string
          The key to the title string in the app’s string resources that you want to use to localize the title text to the user’s current localization. See String Resources for more information.
      • link string
        A deep link (to a page in your app), or a link to a web page.
      • body string
        The body of your push notification.
      • image string
        The URL of an HTTPS image that you want to use for your message.
      • title string
        The title of your push notification.
Copied to clipboard!