This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

41

Live updates

Live notifications let you push real-time, continuously updated notifications to Android devices—a delivery tracker, a live score, a countdown. Use built-in templates or create your own, and let Customer.io push real-time updates to the notification shade panel.

On Android 16 and later, live notifications render with the platform’s promoted “Live Updates” treatment; on earlier versions, they gracefully fall back to standard ongoing notifications with the same content.

Unlike iOS—where you build the activity UI yourself—the Android SDK ships built-in templates. The SDK bundles two: a multi-step tracker (Segments) for delivery or any step-based progress, and a countdown timer. For anything else, define a custom type and render the notification in your own code.

See How live notifications work to learn more about the live notification lifecycle.

To get Android 16’s promoted “Live Updates” treatment, declare the POST_PROMOTED_NOTIFICATIONS permission in your app’s manifest. Without it, live notifications still render as ongoing notifications on Android 16.

<uses-permission android:name="android.permission.POST_PROMOTED_NOTIFICATIONS" />

Step 1: Enable notification types

You must enable at least one type of live notification in your push module configuration. Enable built-in template types with enableLiveNotificationTypes, and your own app-rendered types with enableCustomLiveNotificationTypes. The calls are additive—use either or both.

Add the module when you initialize the SDK, and keep a reference if you plan to start live notifications locally.

import io.customer.messagingpush.MessagingPushModuleConfig
import io.customer.messagingpush.ModuleMessagingPushFCM
import io.customer.messagingpush.livenotification.LiveNotificationType

val pushModule = ModuleMessagingPushFCM(
    MessagingPushModuleConfig.Builder()
        // Built-in templates, rendered by the SDK
        .enableLiveNotificationTypes(
            LiveNotificationType.SEGMENTS,
            LiveNotificationType.COUNTDOWN_TIMER
        )
        // Custom types, rendered by your callback (step 3)
        .enableCustomLiveNotificationTypes("io.yourapp.workout")
        .build()
)

Each built-in type has a reverse-DNS identifier that your server uses to target it:

The identifiers match the iOS sample types, so a cross-platform activity can share one notification_type server-side. Each template’s fields are documented in the payload reference.

Step 2: Add branding (optional)

Built-in templates accept app-level branding—an accent color, a small icon, and a logo applied to every live notification the SDK renders from a template.

import io.customer.messagingpush.livenotification.LiveNotificationAsset
import io.customer.messagingpush.livenotification.LiveNotificationBranding

MessagingPushModuleConfig.Builder()
    .setLiveNotificationBranding(
        LiveNotificationBranding(
            companyName = "Your Company",
            accentColor = Color.parseColor("#1B5E20"),
            smallIcon = R.drawable.ic_notification,
            logo = LiveNotificationAsset.Drawable(R.drawable.brand_logo)
        )
    )

• accentColor sets the notification’s accent color.
• smallIcon sets the small icon (the status-bar glyph) for live notifications. It must be a bundled drawable resource.
• logo sets the logo the template renders as the large icon. Wrap a bundled drawable in LiveNotificationAsset.Drawable.

Step 3: Render custom types

If you want to send a notification without a built-in template, you must render it yourself. Implement createLiveNotification and return a complete Notification—or null to fall back to the SDK’s template for built-in types.

import io.customer.messagingpush.data.model.CustomerIOParsedPushPayload
import io.customer.messagingpush.livenotification.CustomerIOLiveNotificationsCallback

class MyLiveNotificationCallback : CustomerIOLiveNotificationsCallback {
    override fun createLiveNotification(
        payload: CustomerIOParsedPushPayload,
        context: Context
    ): Notification? {
        val extras = payload.extras
        // Return null for types you don't render—the SDK's templates
        // handle the built-in ones.
        if (extras.getString("notification_type") != "io.yourapp.workout") return null
        val ended = extras.getString("event") == "end"
        return NotificationCompat.Builder(context, CHANNEL_ID)
            .setSmallIcon(R.drawable.ic_workout)
            .setContentTitle(extras.getString("title"))
            .setOngoing(!ended)
            .build()
    }
}

The activity’s flattened fields arrive in payload.extras with notification_type and the event (start, update, or end). The SDK posts your notification using the activity ID so updates replace it in place. On end, it renders a final non-ongoing notification when content is available; otherwise, it cancels the existing notification. Register the callback with setLiveNotificationCallback on the module config builder.

Step 4: Start an activity

There are two ways to start a live notification activity:

• From your server: You call the API when you’re ready to start a live notification and Customer.io delivers an FCM data message. The SDK renders the notification without your app needing to be open. This is the most common path for notifications like delivery tracking and live scores.
• From your app: Start the activity locally through the push module. Built-in types use typed data classes; custom types take a field map. This is a common path for notifications like a workout progress tracker.

From your server

Call the API to start and update a live notification. Customer.io delivers the FCM data message, and the SDK renders the notification from your payload’s fields. See the payload reference for each template’s fields.

From your app

Start the activity locally through the push module:

import io.customer.messagingpush.livenotification.LiveNotificationData

// Built-in template type
val activityId = pushModule.startLiveNotification(
    LiveNotificationData.Segments(
        header = "Order",
        status = "Order received",
        segmentsTotal = 4,
        segmentsComplete = 1
    )
)

startLiveNotification returns the activity’s generated ID and registers the notification with Customer.io, so your server can take over updates from there. Local starts and ends are reported to Customer.io automatically. Local updates change the notification on the device but aren’t added to the Customer.io delivery timeline.

Then you can update the activity and end it later with the returned id.

// Update and end it later with the returned id
pushModule.updateLiveNotification(
    activityId,
    LiveNotificationData.Segments(
        header = "Order",
        status = "Out for delivery",
        segmentsTotal = 4,
        segmentsComplete = 3
    )
)
pushModule.endLiveNotification(activityId)

Live notification updates and lifecycle

Live notifications are FCM data messages, not display notifications. The SDK renders them directly, updating the notification in place by its instance ID. Because Android renders each message as it arrives, the SDK guards against out-of-order and duplicate deliveries using the message timestamp. When a person logs out, the SDK ends and clears all live notifications on the device.

The notification lifecycle can also end when a person interacts with the notification. When this happens, the SDK ends the activity and clears the notification.

Related pages

• Live notifications overview
• How live notifications work
• Payload reference
• Push notifications on Android