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

10

Live notifications overview

A live notification shows real-time information from your app in places your customer often checks: the iOS Lock Screen or the Android notification panel. Live notifications are things like a food delivery tracker that moves from “Order received” to “Out for delivery,” live updates for a sporting match, or a flight tracker that counts down to arrival.

This is a developer-focused feature. This feature is almost entirely managed through code. You won’t send a message the way you typically do with other channels or message types in Customer.io.

How it works

Unlike other notification types, you render live notifications in your app. Your app or your server starts a notification, and from then on Customer.io pushes content updates straight to the device, so people see the latest information without opening your app. It ends when the updates are done or the person dismisses the notification.

This is a developer-centric feature that involves your app (using the Customer.io SDK), Customer.io, and your server (which starts, updates, and ends notifications).

• Your app (containing the Customer.io SDK): The SDK watches for new notifications, registers the push tokens they need, and reports lifecycle events back to Customer.io. Your app setup differs by platform:
  • iOS: You define your activities’ data models and render each activity with its own widget. See Set up Live Activities on iOS.
  • Android: You can use the SDK’s built-in templates, or you can define custom notification types and render them yourself. See Set up Live Updates on Android.
• Customer.io stores the device tokens the SDK registers and delivers updates to each device when you start, update, or end a notification.
• Your server: triggers each notification’s start, update, and end by calling the API. It targets your customers by identifier—you don’t manage push tokens yourself, and your server never calls APNs or FCM directly.

Manage your live notification with the instance_id

Every live notification has a unique instance_id, which you use to track the lifecycle of and manage updates to the notification. Each instance contains all of the deliveries for content updates over the lifespan of the live notification.

The instance ID is generated in one of two ways:

• When you start a notification from the API: Customer.io generates the instance ID and returns it in the response.
• When the notification starts from your app: the SDK generates the instance ID.

An instance moves through the following states:

Supported platforms & app versions

Live notifications require the native iOS or Android SDKs. They aren’t available for our React Native, Flutter, or Expo SDKs yet.

On Android versions before 16, live notifications render as ongoing notifications, but the content is the same as Android’s Live Update notifications. Your customers still see every update, without the promoted styling.

Push credentials & required notification permissions

Live notifications use your existing push credentials, but the permission story differs by platform.

Firebase imposes one extra requirement: its API identifies the device by an FCM registration token, which only exists after a customer grants permission to receive notifications. So any setup that routes through Firebase—including iOS through Firebase—needs push permissions.

You must also identifyThe Customer.io operation that adds or updates a person. When you identify a person, Customer.io either adds a person if they don’t exist in your workspace, or updates them if they do. Before you identify someone (by their email address or an ID), you can track them anonymously. your app user before you can start an activity. The SDK holds token registrations until you identify a person, and the API rejects requests that target anonymous profiles.

Registering push tokens

Customer.io pushes updates to each device using the tokens the SDK registers, and the token model differs by platform. On both platforms, the SDK registers tokens for identified people only. If a customer hasn’t been identified yet, the SDK holds the registration and sends it when they are.

iOS: two token types

On iOS, ActivityKit issues two different kinds of push tokens, and the SDK registers each with Customer.io automatically.

• A push-to-start token lets Customer.io create a new activity on a device without your app being open. The SDK registers the token as soon as you register an activity type, and re-registers it whenever the OS rotates the token. Push-to-start requires iOS 17.2 or later.
• An instance token is generated when you start an activity. Customer.io uses it to push content updates and the final end event to a specific activity. The SDK sends this token to Customer.io as soon as the activity becomes observable.

Because tokens can rotate, the SDK watches for changes and reports new values to Customer.io so updates flow without interruption.

Android: your existing FCM token

On Android, live notifications reuse the FCM registration token your app already uses for push. There are no separate token types to manage.