Android's Live Notifications deliver live, dynamic content in notifications to enhance user engagement and app interactivity. This is a feature similar to iOS's Live Activities but uses its own set of tools and APIs that enable similar functionalities. Users must have push notification enabled to receive a Live Notification.

Android widgets have provided real-time content directly on the home screen for some time. Widgets, in particular, have been a staple of Android's Live Notification capability, offering customizable, at-a-glance views of app content without the need to open the app itself.

With OneSignal, you'll be able to send and update Live Notifications through the API.

Setup

Requirements

• Your Android project is integrated with the latest version of the OneSignal SDK.
• Android users must have push notification permissions enabled.

1. Setup OneSignal’s Android Notification Service Extension

Follow the instructions for using the Android Notification Service Extension to create a new class in your project that extends OneSignal's NotificationExtenderService. Within this class, you will override methods to intercept and possibly alter notifications before they are displayed to the user.

Create a custom notification layout

Android provides instructions to create a custom notification layout. Sample code can be found on our Github or below. If you would like to contribute to our sample code, please fork, and not clone, the repository.

Use Notification Extender. Instead of the standard NotificationCompat.Builder, use the Notification.setExtender method to modify your notifications for Live Notifications This allows you to apply your custom layout and any additional modifications programmatically.

package com.onesignal.sample.android;

import com.onesignal.notifications.IActionButton;
import com.onesignal.notifications.IDisplayableMutableNotification;
import com.onesignal.notifications.INotificationReceivedEvent;
import com.onesignal.notifications.INotificationServiceExtension;

public class NotificationServiceExtension implements INotificationServiceExtension {
    @Override
    public void onNotificationReceived(INotificationReceivedEvent event) {
        IDisplayableMutableNotification notification = event.getNotification();

        if (notification.getActionButtons() != null) {
            for (IActionButton button : notification.getActionButtons()) {
                // you can modify your action buttons here
            }
        }

        // this is an example of how to modify the notification by changing the background color to blue
        notification.setExtender(builder -> builder.setColor(0xFF0000FF));
        notification.setExtender(builder -> builder.setAutoCancel(false));

        //If you need to perform an async action or stop the payload from being shown automatically,
        //use event.preventDefault(). Using event.notification.display() will show this message again.
    }
}

2. Update the Android Manifest

Sample code can be found on our Github or below. Be sure to update the android:value on line 17 of your project.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:name=".MainApplication"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.OneSignalAndroidSample"
        tools:targetApi="31">
        <meta-data android:name="com.onesignal.NotificationServiceExtension"
            android:value="com.onesignal.sample.android.NotificationServiceExtension" />
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

3. Send notifications with a collapse_id

Always ensure collapse_id is used on all your notifications that should be part of that “Live Activity". If you initiate a Live Update with a collapse_id of 12, then all further updates need to have a collapse_id of 12. If you do not include the same collapse_id, a different notification will display instead of replacing your original Live Update.

If using the API, refer to collapse_id as described in our Push Channel Properties API Reference.

curl -X POST "https://api.onesignal.com/notifications" \
   -H "Content-Type: application/json; charset=utf-8" \
   -H "Authorization: Basic Rest_API_Key" \
   -d '{
       "app_id": "APP_ID",
       "collapse_id": "1",
       "included_segments": ["Subscribed Users"],
       "contents": {"en": "Download Started"},
       "headings": {"en": "Download Progress"},
       "data": {"live_notification_key": "some_key"}
   }'

Optional: Prevent auto dismissal of notifications

To keep a notification visible even after a user taps on it, call builder.setAutoCancel(false) on your notification builder. This prevents the notification from being automatically dismissed, allowing it to stay in the notification tray until explicitly removed by the user or the app.

Test

Multiple Devices

Test your notifications on at least two devices, but ideally several. We recommend testing on an Android 12 and newer, and another an Android 11 or older since Google made a large change to notifications in Android 12.

Verify Live Notifications

Ensure that notifications with the same collapse_id correctly replace each other and that your custom notification layouts display as intended.

Check Auto Dismiss Behavior
If you’ve chosen to prevent auto dismissal, test tapping on the notification to ensure it remains in the notification tray.