Huawei Live Window Push Guide

Preparations

Before using the Huawei Live Window feature, complete the following preparations:

1. Integrate the software development kit (SDK) and the Huawei channel. For more information, see Integrate the Android SDK and Integrate the Huawei channel.

2. Design your Live Window notification template based on the style templates. For more information, see Live Window Design Specifications.

3. Request the Live Window permission in AppGallery Connect. For more information, see Enable the Service.

4. Create a project-level service account key in the API Console of Huawei Developers and configure the Huawei Live Window service account key in the EMAS console. For more information, see Create Project-level Credentials and Configure vendor channel keys.

Getting Started

After completing the preparations, you can use the following example to quickly create a ride-hailing Live Window on the client.

// Get the NotificationManager object.
Context context = getApplicationContext();
String channelId = "test_channel";
int activityId = 1;
NotificationManager notificationManager = (NotificationManager) context.getSystemService(NOTIFICATION_SERVICE);

// Create a notification channel. If a channel already exists, you can reuse it.
NotificationChannel channel = new NotificationChannel(channelId, "test_channel_name", NotificationManager.IMPORTANCE_HIGH);
notificationManager.createNotificationChannel(channel);

// Create a bundle to save the Live Window notification information. Set type to 3, which indicates the progress visualization type.
Bundle liveNotificationData = new Bundle();
liveNotificationData.putInt("notification.live.operation", 0);
liveNotificationData.putString("notification.live.event", "TAXI");
liveNotificationData.putInt("notification.live.type", 3);
liveNotificationData.putCharSequence("notification.live.titleOverlay", "Driver is on the way");
// Create a SpannableString.
SpannableString spannableString = new SpannableString("1.2 km away | 5 minutes");
// Set the color of "1.2 km" to blue (#FF317AF7).
ForegroundColorSpan colorSpan1 = new ForegroundColorSpan(Color.parseColor("#FF317AF7"));
spannableString.setSpan(colorSpan1, 3, 8, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
// Set the color of "5 minutes" to blue (#FF317AF7).
ForegroundColorSpan colorSpan2 = new ForegroundColorSpan(Color.parseColor("#FF317AF7"));
spannableString.setSpan(colorSpan2, 11, 14, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
// Use the SpannableString as the notification content.
liveNotificationData.putCharSequence("notification.live.contentOverlay", spannableString);

// Create a bundle to save the extension parameters for the progress visualization type.
Bundle feature = new Bundle();
feature.putInt("notification.live.feature.progressType", 0);
ArrayList<Parcelable> nodeIcons = new ArrayList<>();
nodeIcons.add(Icon.createWithResource(context, R.drawable.icon1));
nodeIcons.add(Icon.createWithResource(context, R.drawable.icon2));
feature.putParcelableArrayList("notification.live.feature.nodeIcon", new ArrayList<>(nodeIcons));
feature.putParcelable("notification.live.feature.indicatorIcon", Icon.createWithResource(context, R.drawable.icon3));
feature.putInt("notification.live.feature.indicatorType", 1);
feature.putInt("notification.live.feature.progress", 40);
feature.putInt("notification.live.feature.progressColor", Color.parseColor("#FF317AF7"));
feature.putInt("notification.live.feature.progressBgColor", Color.parseColor("#19000000"));
feature.putInt("notification.live.feature.extendType", 3);
feature.putParcelable("notification.live.feature.extendImage", Icon.createWithResource(context, R.drawable.icon4));

// Create a bundle to save the extension parameters for the Live Window capsule.
Bundle capsule = new Bundle();
capsule.putInt("notification.live.capsuleStatus", 1);
capsule.putInt("notification.live.capsuleType", 1);
capsule.putParcelable("notification.live.capsuleIcon", Icon.createWithResource(context, R.drawable.icon5));
capsule.putInt("notification.live.capsuleBgColor", Color.parseColor("#FF317AF7"));
capsule.putString("notification.live.capsuleTitle", "Picking up");
capsule.putString("notification.live.capsuleContent", "ETA 5 minutes");
capsule.putBoolean("notification.live.capsuleRemind", true);

// Set the extension parameters in the Live Window notification parameters.
liveNotificationData.putBundle("notification.live.capsule", capsule);
liveNotificationData.putBundle("notification.live.feature", feature);

// Create a small icon.
Icon smallIcon = Icon.createWithResource(context, R.drawable.icon6);

// Create a notification and call addExtras to add the Live Window notification information.
Notification notification = new Notification.Builder(context, channelId)
                .setContentTitle("Driver is on the way")
		.setContentText("1.2 km away | 5 minutes")
		.addExtras(liveNotificationData)
		.setSmallIcon(smallIcon)
		.build();

// Send the Live Window notification.
notificationManager.notify(activityId, notification);

The client displays the following:

Core concepts

Huawei Live Window is a new type of notification provided by Huawei HMS Core Push Service. It helps users focus on ongoing tasks for quick viewing and instant processing. Mobile Push now supports remote updates and termination of Huawei Live Windows, providing developers with convenient management capabilities.

What is a Live Window

A Live Window is a periodic, time-sensitive, and dynamic notification. It can appear on the always-on display (AOD), lock screen, notification center, and status bar. It has three main display formats: capsule, card, and small foldable outer screen display.

Core features

• Time-bound: An event or service must have a specific duration with a defined start and end.

• Time-sensitive: The content represents an ongoing or real-time event that is valuable to the user within a specific timeframe.

• Dynamic: The displayed content must be dynamically updated to ensure users see the latest status.

Notification methods

Like regular notifications, a Live Window can display a card on the lock screen and in the notification center. It also supports a capsule format in the status bar and on the AOD. Tapping the capsule in the status bar expands a floating card. These multiple display methods deliver information to users instantly, so they do not need to repeatedly enter and exit the application or service page. The notification center displays all notifications. Other display locations render notifications based on user settings and business importance. For more information about the styles of each display method, see Live Notifications.

1. Live Window notification cards in the notification center are displayed at the top by default, sorted by creation time. The most recently created notification appears first. This prevents overuse from disturbing users.

2. The status bar capsule can be displayed based on business requirements and user needs. This avoids excessive display that occupies the status bar for too long.

3. A single event appears in only one form across different scenarios. For example, if the landing page for the current event is in the foreground, no capsule is displayed. If the user is on the notification center or lock screen, the capsule is not shown.

Basic interactions

Tap the capsule to show the floating card. The capsule disappears. Tap the blank area of the card to go to the corresponding product page.

Supported scenarios for Live Window

Live Window style templates

The card state of a Live Window supports three sections: a fixed area, an auxiliary area, and an extension area. The fixed area is required. The auxiliary and extension areas are optional.

Basic type template

The basic type template is used for scenarios such as calls, transfer progress, and recordings.

Progress visualization template

The progress visualization template is used for scenarios that require showing the complete process and the current progress node, such as ride-hailing and food delivery.

Emphasized text template

The emphasized text template is used for scenarios that require emphasizing parts of the text, such as food pickup and queuing.

Left-right text template

The left-right text template is used for scenarios with symmetrical left and right information, such as high-speed rail and flights.

Match score template

The match score template is used for scenarios such as sports match scores and gaming tournament scores.

Create, update, or end a Live Window locally on the client

When the application process is active, you can manage the Live Window locally on the client using the native Android notification API. For specific steps, see Build Local Live Window Notifications. For parameter descriptions, see Live Window Notifications. You can set the notification.live.operation parameter to 0, 1, or 2 to create, update, or terminate the Live Window, respectively.

Sample code

// Get the NotificationManager object.
Context context = getApplicationContext();
String channelId = "test_channel";
int activityId = 1;
NotificationManager notificationManager = (NotificationManager) context.getSystemService(NOTIFICATION_SERVICE);

// Create a notification channel. If a channel already exists, you can reuse it.
NotificationChannel channel = new NotificationChannel(channelId, "test_channel_name", NotificationManager.IMPORTANCE_HIGH);
notificationManager.createNotificationChannel(channel);

// Create a bundle to save the Live Window notification information. Set type to 3, which indicates the progress visualization type.
Bundle liveNotificationData = new Bundle();
liveNotificationData.putInt("notification.live.operation", 0);
liveNotificationData.putString("notification.live.event", "TAXI");
liveNotificationData.putInt("notification.live.type", 3);
liveNotificationData.putCharSequence("notification.live.titleOverlay", "Driver is on the way");
// Create a SpannableString.
SpannableString spannableString = new SpannableString("1.2 km away | 5 minutes");
// Set the color of "1.2 km" to blue (#FF317AF7).
ForegroundColorSpan colorSpan1 = new ForegroundColorSpan(Color.parseColor("#FF317AF7"));
spannableString.setSpan(colorSpan1, 3, 8, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
// Set the color of "5 minutes" to blue (#FF317AF7).
ForegroundColorSpan colorSpan2 = new ForegroundColorSpan(Color.parseColor("#FF317AF7"));
spannableString.setSpan(colorSpan2, 11, 14, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
// Use the SpannableString as the notification content.
liveNotificationData.putCharSequence("notification.live.contentOverlay", spannableString);

// Create a bundle to save the extension parameters for the progress visualization type.
Bundle feature = new Bundle();
feature.putInt("notification.live.feature.progressType", 0);
ArrayList<Parcelable> nodeIcons = new ArrayList<>();
nodeIcons.add(Icon.createWithResource(context, R.drawable.icon1));
nodeIcons.add(Icon.createWithResource(context, R.drawable.icon2));
feature.putParcelableArrayList("notification.live.feature.nodeIcon", new ArrayList<>(nodeIcons));
feature.putParcelable("notification.live.feature.indicatorIcon", Icon.createWithResource(context, R.drawable.icon3));
feature.putInt("notification.live.feature.indicatorType", 1);
feature.putInt("notification.live.feature.progress", 40);
feature.putInt("notification.live.feature.progressColor", Color.parseColor("#FF317AF7"));
feature.putInt("notification.live.feature.progressBgColor", Color.parseColor("#19000000"));
feature.putInt("notification.live.feature.extendType", 3);
feature.putParcelable("notification.live.feature.extendImage", Icon.createWithResource(context, R.drawable.icon4));

// Create a bundle to save the extension parameters for the Live Window capsule.
Bundle capsule = new Bundle();
capsule.putInt("notification.live.capsuleStatus", 1);
capsule.putInt("notification.live.capsuleType", 1);
capsule.putParcelable("notification.live.capsuleIcon", Icon.createWithResource(context, R.drawable.icon5));
capsule.putInt("notification.live.capsuleBgColor", Color.parseColor("#FF317AF7"));
capsule.putString("notification.live.capsuleTitle", "Picking up");
capsule.putString("notification.live.capsuleContent", "ETA 5 minutes");
capsule.putBoolean("notification.live.capsuleRemind", true);

// Set the extension parameters in the Live Window notification parameters.
liveNotificationData.putBundle("notification.live.capsule", capsule);
liveNotificationData.putBundle("notification.live.feature", feature);

// Create a small icon.
Icon smallIcon = Icon.createWithResource(context, R.drawable.icon6);

// Create a notification and call addExtras to add the Live Window notification information.
Notification notification = new Notification.Builder(context, channelId)
                .setContentTitle("Driver is on the way")
		.setContentText("1.2 km away | 5 minutes")
		.addExtras(liveNotificationData)
		.setSmallIcon(smallIcon)
		.build();

// Send the Live Window notification.
notificationManager.notify(activityId, notification);

Remotely update or end a Live Window using the Mobile Push API

Mobile Push supports remotely updating or ending a Live Window through the Push or MassPush API.

Parameter settings

When calling the API, note the following key parameters:

• PushType: Set to NOTICE when pushing a Live Window.

• AndroidTargetUserType or AndroidHuaweiTargetUserType: Set to 1 for test messages and 0 for official messages.

• AndroidHuaweiLiveNotificationPayload: A JSON string representing the LiveNotificationPayload data structure for a live activity, where the operation field is set to 1/2 to update or end the activity, respectively.

The structure of LiveNotificationPayload is shown in the following table:

Sample code

PushRequest pushRequest = new PushRequest();
// Basic parameters
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("ANDROID");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setAndroidTargetUserType(1);

// Set the parameters for remotely updating the Live Window.
String updateLiveViewPayload = """
{
    "activityId": 1,
    "operation": 1,
    "event": "TAXI",
    "activityData": {
        "notificationData": {
            "type": 3,
            "contentTitle": "Driver has arrived at the pickup point",
            "contentText": [
                {
                    "text": "Away"
                },
                {
                    "text": "0.5 km",
                    "foregroundColor": "#FF317AF7"
                },
                {
                    "text": " | "
                },
                {
                    "text": "2 minutes",
                    "foregroundColor": "#FF317AF7"
                }
            ],
            "clickAction": {
                "actionType": 1,
                "action": "xxxxxx"
            },
            "richProgress": {
                "type": 0,
                "nodeIcons": [
                    "res/drawable/icon1",
                    "res/drawable/icon2"
                ],
                "indicatorIcon": "res/drawable/icon3",
                "progress": 80,
                "indicatorType": 1,
                "color": "#FF317AF7",
                "bgColor": "#19000000"
            },
            "extend": {
                "type": 3,
                "image": "res/drawable/icon4",
                "clickAction": {
                    "actionType": 0
                }
            }
        },
        "capsuleData": {
            "type": 1,
            "status": 1,
            "icon": "res/drawable/icon5",
            "bgColor": "#FF317AF7",
            "remind": true,
            "title": "Driver has arrived at the pickup point",
            "content": "ETA 2 minutes"
        }
    }
}
""";
pushRequest.setAndroidHuaweiLiveNotificationPayload(updateLiveViewPayload);

// Send the push message.
PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n", 
    pushResponse.getRequestId(), pushResponse.getMessageId());

PushRequest pushRequest = new PushRequest();
// Basic parameters
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("ANDROID");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setAndroidTargetUserType(1);

// Set the parameters for remotely ending the Live Window.
String updateLiveViewPayload = """
{
    "activityId": 1,
    "operation": 2,
    "event": "TAXI",
    "activityData": {
        "notificationData": {
            "type": 3,
            "contentTitle": "Driver has arrived at the pickup point",
            "contentText": [
                {
                    "text": "Away"
                },
                {
                    "text": "0.5 km",
                    "foregroundColor": "#FF317AF7"
                },
                {
                    "text": " | "
                },
                {
                    "text": "2 minutes",
                    "foregroundColor": "#FF317AF7"
                }
            ],
            "clickAction": {
                "actionType": 1,
                "action": "xxxxxx"
            },
            "richProgress": {
                "type": 0,
                "nodeIcons": [
                    "res/drawable/icon1",
                    "res/drawable/icon2"
                ],
                "indicatorIcon": "res/drawable/icon3",
                "progress": 80,
                "indicatorType": 1,
                "color": "#FF317AF7",
                "bgColor": "#19000000"
            },
            "extend": {
                "type": 3,
                "image": "res/drawable/icon4",
                "clickAction": {
                    "actionType": 0
                }
            }
        },
        "capsuleData": {
            "type": 1,
            "status": 1,
            "icon": "res/drawable/icon5",
            "bgColor": "#FF317AF7",
            "remind": true,
            "title": "Driver has arrived at the pickup point",
            "content": "ETA 2 minutes"
        }
    }
}
""";
pushRequest.setAndroidHuaweiLiveNotificationPayload(updateLiveViewPayload);

// Send the push message.
PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n", 
    pushResponse.getRequestId(), pushResponse.getMessageId());

Live Window limitations

• Live Window is supported on all models with HarmonyOS 4.0 or later.

• The small foldable outer screen display is currently only supported on HUAWEI Pocket 2 devices. Applications can be adapted accordingly.

• When remotely updating a Live Window notification through Mobile Push, a single activity supports a maximum of 10 refreshes every 5 minutes and 60 refreshes per hour. Updates exceeding this frequency are discarded and not sent.

• To ensure that users see new and valuable content, the maximum time a Live Window notification can go without being refreshed is 2 hours. If a Live Window notification is not updated for more than 2 hours, the system considers it ended.

Troubleshooting

Failed to create a Live Window

1. Check whether you have requested the Live Window permission for the corresponding scenario in AppGallery Connect.

2. Check if the device model runs HarmonyOS 4.0 or later.

3. Check if notification permissions are enabled on the device.

4. Check if the NotificationChannel was created successfully.

Failed to update or end a Live Window

1. Check if the activityId in the AndroidHuaweiLiveNotificationPayload parameter matches the activityId used when creating the Live Window.

2. Check if the version in the AndroidHuaweiLiveNotificationPayload parameter is set correctly.

3. Check if the frequency limit was triggered.

4. Use the message ID and device ID in the Mobile Push console on the Troubleshooting -> Troubleshoot Message page to check the Live Window push link.

Abnormal Live Window style

1. Check if the type in the AndroidHuaweiLiveNotificationPayload parameter matches the corresponding template.

2. Check if the resource file path is correct.