Android live notifications
Create and update dynamic, real-time notifications on Android devices using OneSignal Live Notifications. Deliver continuously updated content inside a single notification, simulating iOS Live Activities for Android.
OneSignal’s Android Live Notifications let you send real-time updates to a single notification, reducing clutter and improving engagement. These notifications remain persistent and update their content dynamically—ideal for sports scores, download progress, or event tracking.
To receive Live Notifications, Android users must have push notifications enabled.
Requirements
- Your app must use the latest version of the OneSignal SDK.
- Android users must have push notification permissions enabled.
Live notifications vs. standard push
Unlike regular push notifications, which send a new notification each time, Live Notifications use a single notification updated over time. Updates are sent via the Create Message API using the same collapse_id
.
Configuration
1. Implement a Notification Service Extension
Create a NotificationServiceExtension
class that implements INotificationServiceExtension
. This class intercepts incoming notifications and can modify or override them.
Refer to Android Notification Service Extension for more details.
2. Add the extension to the Android Manifest
3. Create Live Notification types
A Live Notification Type indicates which Live Notification to start.
Define keys
Live Notifications are referenced by a key
, which determines how updates are routed.
Create notification channels
Channels define how notifications behave (sound, vibration, appearance). You must create channels for your Live Notification types. We recommend:
- Low Importance for progress notifications
- Disable badges
- Keep sound and vibration to a minimum
See Android Notification Channel Categories for more information.
Design the Live Notification
When designing a Live Notification, you have the flexibility to create a notification design for each update type. Each design you create must be assigned a specific type, allowing for varied presentations of a Live Notification.
Design considerations:
- Small icon & accent color
- Large icon
- Big picture
- Action buttons
See Android custom notification layout for advanced design options.
4. Extract the Live Notification payload
Live Notifications use the additional_data
field to pass structured content.
Live Notification Schema
Property | Required | Description |
---|---|---|
key | Yes | Used to load the correct notification UI. |
event | Yes | The action to perform on the Live Notification. |
event_attributes | No | Static data is used to initialize the Live Notification; a Self-defined schema that defines the data your notification needs. |
event_updates | No | Dynamic content of the Live Notification. Must conform to the ContentState interface defined within your app’s Live Notification. |
5. Handle Live Notification events
Each Live Notification must respond to the following events:
Event | Description | Required fields |
---|---|---|
start | Begins a Live Notification with static and dynamic data. | event_attributes , event_updates |
update | Updates the Live Notification with new dynamic data. | event_updates |
end | Ends and removes the Live Notification. | None |
Start a Live Notification
When you are ready to start a Live Notification:
- Set
event_attributes
to initialize the static data for the Live Notification. This data will not change during the lifetime of the Live Notification. - Set
event_updates
data to initialize the dynamic data for the Live Notification. This is the data that can and will change during the lifetime of the Live Notification. - A
collapse_id
to make sure each update overrides the previous. This ID should be unique to the Live Notification to ensure subsequent updates are reflected in the same notification.
Update Live Notification
You can update the Live Notification as many times as you like, so long as it’s started first.
- Set
event_updates
data to initialize the dynamic data for the Live Notification. This is the data that can and will change during the lifetime of the Live Notification and informs what to update your Live Notification’s content with.
Example cURL request
End Live Notification
Example cURL request
You have successfully created a Live Notification!
Related docs: