HarmonyOS Live View push guide

Preparations

Before you can use the HarmonyOS Live View feature, you must complete the following preparations:

1. Integrate the software development kit (SDK) and register the HarmonyOS PushToken. For more information, see Integrate the HarmonyOS SDK.

2. Design your Live View notification template based on the provided style templates. For more information, see Live View design specifications.

3. Request the Live View permission in AppGallery Connect. For more information, see Development preparations.

Getting started

After you complete the preparations, you can use the following example to quickly create a Live View for a ride-hailing service:

PushRequest pushRequest = new PushRequest();
// Basic parameters
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// Set parameters to remotely create a Live View
String startLiveViewPayload = """
{
  "activityId": 1,
  "operation": 0,
  "event": "TAXI",
  "status": "DRIVER_ON_THE_WAY",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "Distance to you"
        },
        {
          "text": "1.2 km",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "5 minutes",
          "foregroundColor": "#FF317AF7"
        }
      ],
      "clickAction": {
        "actionType": 1,
        "action": "xxxxxx"
      },
      "richProgress": {
        "type": 0,
        "nodeIcons": ["icon1.png", "icon2.png", "icon3.png"],
        "indicatorIcon": "taxi.png",
        "progress": 40,
        "indicatorType": 1,
        "color": "#FF317AF7",
        "bgColor": "#19000000"
      },
      "extend": {
        "type": 3,
        "pic": "phone.png",
        "clickAction": {
          "actionType": 0
        }
      }
    },
    "capsuleData": {
      "type": 1,
      "status": 1,
      "icon": "icon.svg",
      "bgColor": "#FF317AF7",
      "remind": "EXPAND",
      "title": "Driver en route",
      "content": "ETA 5 minutes"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(startLiveViewPayload);

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

The client displays the following:

Core concepts

HarmonyOS Live View is a new notification type in the HarmonyOS NEXT system. It helps users focus on ongoing tasks by providing quick-view and immediate-action capabilities. Mobile Push now supports creating, updating, and ending Live Views, which gives developers a simple way to manage them.

What is a Live View?

A Live View is a notification type that is time-bound, time-sensitive, and dynamic. It can be displayed on the lock screen, in the notification center, and on the status bar. It has two main display formats: capsule and card.

Core features

• Time-bound: The event or service has a defined duration with a clear start and end time.

• Time-sensitive: The content relates to an ongoing or real-time event that is valuable to the user for a limited period.

• Dynamic: The displayed content updates dynamically to reflect the latest status.

Reminder methods

Live View can display cards on the lock screen and in the notification center. It also supports the following features:

1. Displaying a capsule on the status bar. When a user taps the capsule, it expands into a floating card.

2. Displaying a capsule and a card on the lock screen. A user can long-press or tap the card's header image to enter an immersive lock screen mode.

These multiple display methods deliver information to users instantly. This prevents users from having to repeatedly open and close application or service pages. By default, the notification center displays all Live Views at the top. In other locations, Live Views are displayed based on user settings and business importance. For more information about the styles of different display methods, see Live View.

1. A single event appears in only one form at a time. For example, if the event's landing page is in the foreground, no capsule is displayed. If the user is viewing the notification center or lock screen, the status bar capsule is not shown.

2. Live View cards appear at the top of the notification center by default. You should avoid overusing this feature to prevent disturbing users.

Basic interactions

When a user taps a capsule, a floating card is displayed and the capsule disappears. Tapping the blank area of the card navigates the user to the corresponding details page.

Entering immersive mode: This is the default mode after the screen is locked. You can also enter this mode by tapping the header image of a lock screen card or by tapping a lock screen capsule.

Exiting immersive mode: Use the side back gesture to return to the previous state. You can swipe down to collapse the view into a capsule or swipe up to enter the lock screen card state.

Supported scenario types for Live View

The three operation types for Live Views (create, update, and end) have the following restrictions for each scenario:

Live View style templates

A Live View card consists of three sections: a fixed area, an auxiliary area, and an extension area. The fixed area is required, while the auxiliary and extension areas are optional.

Progress visualization template

The progress visualization template is suitable for scenarios such as ride-hailing and food delivery.

Emphasized text template

The emphasized text template is suitable for scenarios such as pickup and queuing.

Side-by-side text template

The side-by-side text template is suitable for scenarios such as high-speed rail and flights.

Match score template

The match score template is suitable for sports match scenarios.

Navigation template

The navigation template is suitable for travel navigation scenarios.

Create, update, or end a Live View locally using the HarmonyOS Live View Kit

When the application process is active, you can manage a Live View locally on the client using the liveViewManager of the HarmonyOS Live View Kit. The startLiveView, updateLiveView, and stopLiveView methods are used to create, update, and end a Live View, respectively. For the code for each template, see Build a local Live View. For more information about the data structure of a Live View, see liveViewManager.LiveView.

Remotely create, update, or end a Live View using the Mobile Push API

Mobile Push supports remotely creating, updating, and ending Live Views using the Push or MassPush API. Remote creation is only supported for the Flight (FLIGHT), Ride-hailing (TAXI), and High-speed rail/Train (TRAIN) scenarios. There are no scenario restrictions for updating or ending Live Views.

Parameter settings

When you call the API, take note of the following key parameters:

• PushType: Set this parameter to NOTICE to indicate that a live window is pushed.

• HarmonyTestMessage: Set to true for test messages and false for official messages.

• HarmonyLiveViewPayload: The JSON string of the LiveViewPayload data structure. Set the operation parameter to 0 to create, 1 to update, or 2 to end a Live View.

The structure of LiveViewPayload is shown in the following table:

Example code

PushRequest pushRequest = new PushRequest();
// Basic parameters
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// Set parameters to remotely create a Live View
String startLiveViewPayload = """
{
  "activityId": 1,
  "operation": 0,
  "event": "TAXI",
  "status": "DRIVER_ON_THE_WAY",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "Distance to you"
        },
        {
          "text": "1.2 km",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "5 minutes",
          "foregroundColor": "#FF317AF7"
        }
      ],
      "clickAction": {
        "actionType": 1,
        "action": "xxxxxx"
      },
      "richProgress": {
        "type": 0,
        "nodeIcons": ["icon1.png", "icon2.png", "icon3.png"],
        "indicatorIcon": "taxi.png",
        "progress": 40,
        "indicatorType": 1,
        "color": "#FF317AF7",
        "bgColor": "#19000000"
      },
      "extend": {
        "type": 3,
        "pic": "phone.png",
        "clickAction": {
          "actionType": 0
        }
      }
    },
    "capsuleData": {
      "type": 1,
      "status": 1,
      "icon": "icon.svg",
      "bgColor": "#FF317AF7",
      "remind": "EXPAND",
      "title": "Driver en route",
      "content": "ETA 5 minutes"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(startLiveViewPayload);

// 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("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// Set parameters to remotely update a Live View
String updateLiveViewPayload = """
{
  "activityId": 1,
  "operation": 1,
  "event": "TAXI",
  "status": "DRIVER_ARRIVE",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "Distance to you"
        },
        {
          "text": "0.5 km",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "2 minutes",
          "foregroundColor": "#FF317AF7"
        }
      ],
      "clickAction": {
        "actionType": 1,
        "action": "xxxxxx"
      },
      "richProgress": {
        "type": 0,
        "nodeIcons": ["icon1.png", "icon2.png", "icon3.png"],
        "indicatorIcon": "taxi.png",
        "progress": 40,
        "indicatorType": 1,
        "color": "#FF317AF7",
        "bgColor": "#19000000"
      },
      "extend": {
        "type": 3,
        "pic": "phone.png",
        "clickAction": {
          "actionType": 0
        }
      }
    },
    "capsuleData": {
      "type": 1,
      "status": 1,
      "icon": "icon.svg",
      "bgColor": "#FF317AF7",
      "remind": "EXPAND",
      "title": "Driver has arrived at the pickup point",
      "content": "ETA 2 minutes"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(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("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// Set parameters to remotely end a Live View
String stopLiveViewPayload = """
{
  "activityId": 1,
  "operation": 2,
  "event": "TAXI",
  "status": "DRIVER_ARRIVE",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "Distance to you"
        },
        {
          "text": "0.5 km",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "2 minutes",
          "foregroundColor": "#FF317AF7"
        }
      ],
      "clickAction": {
        "actionType": 1,
        "action": "xxxxxx"
      },
      "richProgress": {
        "type": 0,
        "nodeIcons": ["icon1.png", "icon2.png", "icon3.png"],
        "indicatorIcon": "taxi.png",
        "progress": 40,
        "indicatorType": 1,
        "color": "#FF317AF7",
        "bgColor": "#19000000"
      },
      "extend": {
        "type": 3,
        "pic": "phone.png",
        "clickAction": {
          "actionType": 0
        }
      }
    },
    "capsuleData": {
      "type": 1,
      "status": 1,
      "icon": "icon.svg",
      "bgColor": "#FF317AF7",
      "remind": "EXPAND",
      "title": "Driver has arrived at the pickup point",
      "content": "ETA 2 minutes"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(stopLiveViewPayload);

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

Live View limitations

Lifecycle limitations

• A single Live View has a maximum lifecycle of 8 hours. After 8 hours, the system automatically ends the Live View.

• If a Live View is not updated for more than 2 hours, its status bar capsule and lock screen display are hidden. However, it is still displayed in the notification center.

• If a Live View is not updated for more than 4 hours, the system automatically ends it and purges it from all display locations.

• A user can delete a Live View notification at any time. After a Live View is deleted, subsequent updates to it will not be displayed.

Frequency limitations

Testing phase:

• Each project can push a maximum of 1,000 test messages per day. To push test messages, set HarmonyTestMessage to true.

Official phase:

• The total number of messages that can be pushed to a single device from a single application per day is limited by device message frequency control. The total number of all scenario-based messages sent cannot exceed 3,000.

• For a single Live View, the update frequency varies by scenario. For the Ride-hailing and Match score scenarios, a Live View can be updated a maximum of 30 times every 5 minutes and 180 times per hour per device. For other scenarios, a Live View can be updated a maximum of 10 times every 5 minutes and 60 times per hour per device. Updates that exceed the frequency limit are discarded and not delivered.

Limitations on remote creation of Live Views

• Remote creation of Live Views using Mobile Push is supported only for the FLIGHT, TAXI, and TRAIN scenarios.

• You cannot remotely create a Live View with the same activityId on the same device using Mobile Push within a 12-hour period.

• When you create a Live View, different event types have the following scenario constraints on the layout type (activityData.notificationData.type) and required fields:

• For different layout types (activityData.notificationData.type), you must include the {{status}} placeholder for status at least once in the fields that support placeholders. If the keywords field is also required for the event, you must also include the corresponding placeholder at least once in the fields that support placeholders. For more information about placeholders, see the description of the keywords field.

• For Live Views created remotely using Mobile Push, updates must meet both the status and keywords requirements. For Live Views created with the Live View Kit (Live View service), you can leave the status and keywords fields empty when you update them remotely with Mobile Push. If you choose to populate these fields, they must meet the status and keywords requirements.

Troubleshooting

Failed to create a Live View

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

2. To check if a device supports Live View, refer to Build a local Live View or call the liveViewManager.isLiveViewEnabled() method.

3. Check whether the frequency limitations have been triggered.

4. For Live Views created remotely using Mobile Push, check whether the limitations on remote creation of Live Views have been triggered.

5. Use the message ID and device ID to check the Live View push link on the **Troubleshoot Message** page of the Mobile Push console.

Failed to update or end a Live View

1. Check whether the activityId in the HarmonyLiveViewPayload parameter is the same as the one used when the Live View was created.

2. Check whether the version in the HarmonyLiveViewPayload parameter is set correctly.

3. Check whether the frequency limitations have been triggered.

4. Use the message ID and device ID to check the Live View push link on the **Troubleshoot Message** page of the Mobile Push console.

Abnormal Live View style

1. Check whether the type in the HarmonyLiveViewPayload parameter matches the corresponding template.

2. Check whether the resource file path is correct.