Set up Live Updates

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

How it works

A live notification is an ongoing notification that updates in place—one notification whose content changes as the order moves, the score changes, or the timer counts down. On Android 16 and later, it renders with the platform’s promoted Live Updates ↗ treatment. On earlier versions it falls back to a standard ongoing notification carrying the same content, so your customers still see every update—just without the promoted styling.

The Android SDK ships built-in templates and renders them for you. It 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.

Four actors drive every live notification:

• You enable the notification types your app supports, and supply a renderer for any custom types.
• The SDK renders each update—built-in templates directly, your custom types through your renderer—and reports lifecycle events to Customer.io.
• Your server starts, updates, and ends notifications by calling the API.
• Customer.io delivers each update to the device and records every start, update, and end as a delivery.

Customer.io sits in the middle: your server only ever calls the API, and Customer.io delivers each update to the device, where the SDK renders it—with a built-in template or your own renderer. For the API operations, payload shapes, and template fields, see the API and payload reference.

Before you begin

Live Updates use the FCM credentials your app already has in Customer.io. Two permissions matter:

Declare the promoted permission in your app’s manifest:

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

You must also identify your app user before you can start a notification. The SDK holds token registrations until you identify a person, and the API rejects requests that target anonymous profiles.

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 notification can share one notification_type server-side. Each template’s fields are documented in the API and 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 notification’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.

Because the SDK renders from a merged payload, include any static fields your renderer needs in attributes on update and end calls too—not just on start.

That’s the setup. To create your first live notification—from your server or from your app—see Start Live Updates.