Push notifications

Get started setting up push notifications for Android. Our Android SDK supports push notifications over FCM, including rich push messages with links and images.

This page is part of a setup flow for the SDK. Before you continue, make sure you've implemented previous features—i.e. you can't receive push notifications before you identify people!

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(Write tests) push --> test-support rich-push --> test-support identify -.-> in-app(Receive in-app) in-app --> test-support click getting-started href "/docs/sdk/android/getting-started/#install" 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 register-token href "/docs/sdk/android/push" click push href "/docs/sdk/android/push" click rich-push href "/docs/sdk/android/rich-push" click in-app href "/docs/sdk/android/in-app" click test-support href "/docs/sdk/android/test-support" style push fill:#B5FFEF,stroke:#007069

Before you begin

This page explains how to receive rich push notifications using our SDK. However, before you can send push notifications to your audience, you need to enable Customer.io to send push notifications through Firebase Cloud Messaging (FCM).

 Check out our sample apps!

Our repository provides real-world examples that you can help you see how the SDK works and implement it in your own apps.

How it works

Before a device can receive a push notification, you must:

  1. Set up FCM.
  2. Set up push.
  3. Identify a person. When someone starts the app, they automatically generate a device token. Identifying the person associates the device token with the person in Customer.io, so that they can receive push notifications.
  4. Set up a campaign to send a push notification through the Customer.io composer.

Set up push

  1. You must implement the Push Messaging SDK to use push notification features.

    implementation 'io.customer.android:messaging-push-fcm:<version-here>'
    
  2. Initialize the push module. The push module has an optional config object, explained below. See deep links for help configuring links.

     CustomerIO.Builder(
         siteId = "siteId",
         apiKey = "apiKey",
         appContext = application,
     ).apply {
         addCustomerIOModule(
             ModuleMessagingPushFCM()
         )
         autoTrackScreenViews(true)
         setRequestTimeout(8000L)
         setRegion(Region.US)
         build()
     }

The SDK adds a FirebaseMessagingService to the app manifest automatically, so you don’t have to perform additional setup to handle incoming push messages.

However, if your application implements its own FirebaseMessagingService, make sure that when you call onMessageReceived and onNewToken methods, you also call CustomerIOFirebaseMessagingService.onMessageReceived and CustomerIOFirebaseMessagingService.onNewToken respectively.

class FirebaseMessagingService : FirebaseMessagingService() {

 override fun onMessageReceived(message: RemoteMessage) {
    val handled = CustomerIOFirebaseMessagingService.onMessageReceived(context, message)
    if (handled) {
        logger.breadcrumb(this, "Push notification has been handled", null)
    }
 }
 
override fun onNewToken(token: String) {
    CustomerIOFirebaseMessagingService.onNewToken(context, token)
}

Push notifications launched from the SDK are currently posted to our default channel—[your app name] Channel. In the future, we plan to let you customize channels/categories so that users can subscribe and unsubscribe to content categories as necessary.

Push module configuration

ModuleMesagingPushFCM has an optional configuration object.

The notificationCallback is A callback that notifies client on push notification related actions. For now, this callback is only useful for handling deep links, but we have plans to add more methods in future releases. It defaults to null.

The redirectDeepLinksToOtherApps flag enables (true) or disables (false) the ability to open non app links outside the app. It is true by default.

  • true: links not supported by your app will be opened in other matching apps. If a matching app isn’t found, the host app opens to default landing page.
  • false: unsupported links open the host app to its default landing page.
CustomerIO.Builder(
    siteId = "siteId",
    apiKey = "apiKey",
    appContext = application,
).apply {
    addCustomerIOModule(
        ModuleMessagingPushFCM(
            config = MessagingPushModuleConfig.Builder().apply {
                setNotificationCallback(this)
                setRedirectDeepLinksToOtherApps(false)
            }.build()
        )
    )
    setRegion(Region.US)
    build()
}

Push click behavior

The pushClickBehavior config lets you customize your application’s response when your audience taps a push notification. This includes going to specific deep links or launcher screens based on the notification payload. Note that the SDK tracks opened metrics for all click behaviors.

builder.addCustomerIOModule(
  ModuleMessagingPushFCM(
    config = MessagingPushModuleConfig.Builder().apply {
      setPushClickBehavior(PushClickBehavior.ACTIVITY_PREVENT_RESTART)
    }.build()
  )
)

The available options are:

  • ACTIVITY_PREVENT_RESTART (Default): If your app is already in the foreground, the SDK will not re-create your app when your audience clicks a push notification. Instead, the SDK will reuse the existing activity. If your app is not in the foreground, we’ll launch a new instance of your deep-linked activity. We recommend that you use this setting if your app has screens that your audience shouldn’t navigate away from—like a shopping cart screen.

  • ACTIVITY_NO_FLAGS: If your app is in the foreground, the SDK will re-create your app when your audience clicks a notification. The activity is added on top of the app’s existing navigation stack, so if your audience tries to go back, they will go back to where they previously were.

  • RESET_TASK_STACK: No matter what state your app is in (foreground, background, killed), the SDK will re-create your app when your audience clicks a push notification. Whether your app is in the foreground or background, the state of your app will be killed so your audience cannot to go back to the previous screen if they press the back button.

Capture push metrics

Customer.io supports device-side metrics that help you determine the efficacy of your push notifications: delivered when a push notification is received by the app and opened when a push notification is clicked.

By default, the messaging-push-fcm SDK automatically tracks opened and delivered for push notifications originating from Customer.io. Otherwise, you can track push metrics with the trackMetric method.

CustomerIO.instance().trackMetric(
    deliveryID = deliveryId,
    deviceToken = deliveryToken,
    event = MetricEvent.delivered
)

Deep links provide a way to link to a screen in your app. Our SDK supports redirects for notification links registered in Android by default. You can customize this behavior using CustomerIOPushNotificationCallback.

  • To register a deep link, you must first add intent filters in your AndroidManifest.xml file.

    <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://settings” -->
        <data
            android:host="settings"
            android:scheme="remote-habits" />
    </intent-filter>
    
  • CustomerIOPushNotificationCallback—a URL handler feature provided by the SDK. When configuring your CustomerIO instance, you can set the callback to handle notification behavior.

    class MainApplication : Application(), CustomerIOPushNotificationCallback {
      override fun onCreate() {
        super.onCreate()
        val builder = CustomerIO.Builder(
          siteId = "YOUR-SITE-ID",
          apiKey = "YOUR-API-KEY",
          appContext = this
        )
        builder.addCustomerIOModule(
          ModuleMessagingPushFCM(
            config = MessagingPushModuleConfig.Builder().apply {
              setNotificationCallback(this)
              setRedirectDeepLinksToOtherApps(true)
            }.build()
          )
        )
        builder.build()
      }
    
      override fun createTaskStackFromPayload(
        context: Context,
        payload: CustomerIOParsedPushPayload
      ): TaskStackBuilder? {
        // return TaskStackBuilder of your choice if you plan to handle the deep link yourself
        // and make sure to track notification metrics in the right place
        //
        // return null 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 CustomerIOPushNotificationCallback specified in CustomerIO.Builder object before it looks for default supported links.

The notification handler returns the TaskStackBuilder. If the handler is not set or returns null, the SDK tries to open the link in your app. If your app doesn’t support the link and redirectDeepLinksToOtherApps in the MessagingPushModuleConfig is true, the SDK will open the link in a web browser (if a web browser app is available). By default, redirectDeepLinksToOtherApps is true.

 Don’t forget to capture metrics

When you provide CustomerIOPushNotificationCallback, don’t forget to capture notification metrics, otherwise our dashboards might not show notification conversions properly.

Customizing Push Notifications

You can customize the icon and color of push notifications by updating your AndroidManifest as recommended by FCM.

<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_notification" />
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorNotificationIcon" />

However, if you want more control over your notifications’ appearance and behavior, Customer.io SDK provides an option to override these settings on the app side. You can customize notification appearance by implementing CustomerIOPushNotificationCallback and overriding the onNotificationComposed method.

class MainApplication : Application(), CustomerIOPushNotificationCallback {
  override fun onCreate() {
    super.onCreate()
    val builder = CustomerIO.Builder(
      siteId = "YOUR-SITE-ID",
      apiKey = "YOUR-API-KEY",
      appContext = this
    )
    builder.addCustomerIOModule(
      ModuleMessagingPushFCM(
        config = MessagingPushModuleConfig.Builder().apply {
          setNotificationCallback(this)
          setRedirectDeepLinksToOtherApps(true)
        }.build()
      )
    )
    builder.build()
  }

  override fun onNotificationComposed(
    payload: CustomerIOParsedPushPayload,
    builder: NotificationCompat.Builder
  ) {
    // Customize your notification here
  }
}

Customer.io SDK does not let you override PendingIntent for notifications. If you want to override the behavior when people tap your notifications, you can implement createTaskStackFromPayload as described above in deep links.

Test Rich Push

After you set up your push implementation, you should test it. Simply set up a push notification that includes an image and link.

This is what the payload looks like on our end. If you’ve set up your app to use other data—custom keys outside the scope of our SDK—you can use our Custom Payload Editor; you’re welcome to place custom keys inside the message.data object, but you’ll need to do additional development to support keys beyond our standard title, body, link, and image.

{
  "message": {
    "data": {
      "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
      "link": "string" //Deep link in the format remote-habits://deep?message=hello&message2=world
    }
  }
}
  • message
    Required The parent object for all push payloads.
        • 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 a 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.
      • body string
        The body of your push notification.
      • image string
        The URL of an HTTPS image that you want to use for your message.
      • link string
        A deep link (to a page in your app), or a link to a web page.
      • title string
        The title of your push notification.
Copied to clipboard!
  Contents
Current release
 3.11.0
Is this page helpful?
Chat with AI