HarmonyOS 实况窗推送指南

准备工作

在开始使用鸿蒙实况窗功能之前，您需要完成以下准备工作：

1. 已参考HarmonyOS SDK接入完成SDK的接入，并注册鸿蒙PushToken。

2. 已参考实况窗设计规范依据样式模板设计您的实况窗通知范本。

3. 已参考开发准备在AppGallery Connect中申请实况窗权限。

快速开始

完成准备工作后，您可以通过下面的示例来快速创建一个打车实况窗：

PushRequest pushRequest = new PushRequest();
// 基础参数
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// 设置远程创建实况窗的参数
String startLiveViewPayload = """
{
  "activityId": 1,
  "operation": 0,
  "event": "TAXI",
  "status": "DRIVER_ON_THE_WAY",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "距您"
        },
        {
          "text": "1.2公里",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "5分钟",
          "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": "接驾中",
      "content": "预计5分钟"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(startLiveViewPayload);

// 发送推送
PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n", 
    pushResponse.getRequestId(), pushResponse.getMessageId());

客户端显示如下：

核心概念

鸿蒙实况窗（Live View）是HarmonyOS NEXT系统提供的一种新型通知形态，能够帮助用户聚焦正在进行的任务，方便快速查看和即时处理。移动推送现已支持鸿蒙实况窗的创建、更新和结束操作，为开发者提供便捷的实况窗管理能力。

什么是实况窗

实况窗是一种具有时段性、时效性、变化性特点的通知形态，支持在锁屏、通知中心、状态栏等位置展示，主要有胶囊态和卡片态两种展示形式。

核心特点

• 时段性：事件或服务需要持续一段时间，有明确的开始和结束。

• 时效性：内容为正在进行或即时发生的事件，在特定时间段内对用户有价值。

• 变化性：展示的内容需要动态更新，确保用户看到最新状态。

提醒方式

实况窗能够在锁屏、通知中心等位置显示卡片。除此之外，还支持：

1. 在状态栏显示胶囊状态，以及在状态栏点击胶囊后展开悬浮卡片。

2. 在锁屏显示胶囊状态和卡片态，以及长按或点击卡片头图进入锁屏沉浸态。

多种显示方式能够将信息即时触达到用户，避免用户反复进出应用或服务的页面。在不同的显示位置中，通知中心顶部会显示全量实况窗，其他显示位置则根据用户的设置及业务的重要程度进行呈现。各种显示方式的详细样式请参考实况窗。

1. 同一个事件活动在不同场景下仅出现一个形态，如当前事件所承载的落地页在前台，则当前无胶囊；如当前为通知中心/锁屏，则不显示状态栏胶囊。

2. 通知中心的实况卡片会默认显示在顶部，需避免滥用对用户造成打扰。

基础交互

点击单个胶囊，呼出悬浮卡片，胶囊消失；点击卡片空白处，进入对应详情页。

进入沉浸态：锁屏后默认进入；点击锁屏卡片态头图；点击锁屏胶囊态。

退出沉浸态：侧边back手势退出，返回至展开前状态；下拉收起至胶囊态；上滑进入锁屏卡片态。

实况窗支持的场景类型

实况窗的三种操作类型对于各场景的限制如下：

实况窗样式模板

实况窗的卡片态支持固定区、辅助区、扩展区三个板块，其中固定区为必选，辅助区和扩展区为可选。

进度可视化模板

进度可视化模板适用于打车、外卖等场景。

强调文本模板

强调文本模板适用于取餐、排队等场景。

左右文本模板

左右文本模板适用于高铁、航班等场景。

赛事比分模板

赛事比分模板适用于赛事场景。

导航模板

导航模板适用于出行导航场景。

通过鸿蒙Live View Kit本地创建/更新/结束实况窗

应用进程活跃时，可以通过鸿蒙Live View Kit的liveViewManager在客户端本地操作实况窗，其中startLiveView/updateLiveView/stopLiveView分别为创建/更新/结束实况窗的方法。具体各模板的代码请参考构建本地实况窗，实况窗的数据结构请参考liveViewManager.LiveView。

通过移动推送接口远程创建/更新/结束实况窗

移动推送支持通过Push接口或MassPush接口远程创建/更新/结束实况窗，其中创建只支持航班（FLIGHT）、出行打车（TAXI）、高铁/火车（TRAIN）三种场景，更新与结束无场景限制。

参数设置

调用接口时注意以下关键参数：

• PushType: 推送实况窗时固定设置为 NOTICE。

• HarmonyTestMessage: 测试消息设置为 true，正式消息设置为false。

• HarmonyLiveViewPayload: 实况窗数据结构LiveViewPayload的JSON字符串，其中operation在创建/更新/结束时分别设置为0/1/2。

LiveViewPayload的结构如下表所示：

示例代码

PushRequest pushRequest = new PushRequest();
// 基础参数
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// 设置远程创建实况窗的参数
String startLiveViewPayload = """
{
  "activityId": 1,
  "operation": 0,
  "event": "TAXI",
  "status": "DRIVER_ON_THE_WAY",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "距您"
        },
        {
          "text": "1.2公里",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "5分钟",
          "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": "接驾中",
      "content": "预计5分钟"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(startLiveViewPayload);

// 发送推送
PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n", 
    pushResponse.getRequestId(), pushResponse.getMessageId());

PushRequest pushRequest = new PushRequest();
// 基础参数
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// 设置远程更新实况窗的参数
String updateLiveViewPayload = """
{
  "activityId": 1,
  "operation": 1,
  "event": "TAXI",
  "status": "DRIVER_ARRIVE",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "距您"
        },
        {
          "text": "0.5公里",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "2分钟",
          "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": "司机已到达上车点",
      "content": "预计2分钟"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(updateLiveViewPayload);

// 发送推送
PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n", 
    pushResponse.getRequestId(), pushResponse.getMessageId());

PushRequest pushRequest = new PushRequest();
// 基础参数
pushRequest.setAppKey(appKey);
pushRequest.setPushType("NOTICE");
pushRequest.setDeviceType("HARMONY");
pushRequest.setTarget(target);
pushRequest.setTargetValue(targetValue);
pushRequest.setHarmonyTestMessage(true);

// 设置远程结束实况窗的参数
String stopLiveViewPayload = """
{
  "activityId": 1,
  "operation": 2,
  "event": "TAXI",
  "status": "DRIVER_ARRIVE",
  "activityData": {
    "notificationData": {
      "type": 3,       
      "contentTitle": "{{status}}",
      "contentText": [
        {
          "text": "距您"
        },
        {
          "text": "0.5公里",
          "foregroundColor": "#FF317AF7"
        },
        {
          "text": " | "
        },
        {
          "text": "2分钟",
          "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": "司机已到达上车点",
      "content": "预计2分钟"
    }
  }
}
""";
pushRequest.setHarmonyLiveViewPayload(stopLiveViewPayload);

// 发送推送
PushResponse pushResponse = client.getAcsResponse(pushRequest);
System.out.printf("RequestId: %s, MessageId: %s\n", 
    pushResponse.getRequestId(), pushResponse.getMessageId());

实况窗限制

生命周期限制

• 单个实况窗最长生命周期不超过8小时，超过8小时后系统会认为实况窗结束。

• 超过2小时未更新会隐藏状态栏胶囊和锁屏展示，保留通知中心展示。

• 超过4小时未更新，系统会认为实况窗结束，并从各个展示入口清除该实况窗。

• 用户可以在实况窗通知展示的任何时间点对某一实况窗通知进行删除，删除后，该实况窗通知的更新将不再展示。

频率限制

测试阶段：

• 每个项目每日最多推送1000条测试消息，推送测试消息需要设置HarmonyTestMessage为true

正式阶段：

• 单设备单应用下每日推送消息总条数受设备消息频控限制，所有场景化消息发送条数不超过3000条。

• 单个实况窗消息，出行打车与赛事比分场景每个设备每5分钟最多更新30次，每小时最多更新180次。其余场景每个设备每5分钟最多更新10次，每小时最多更新60次。超过频次部分将丢弃不下发。

远程创建实况窗限制

• 通过移动推送远程创建实况窗仅支持FLIGHT、TAXI、TRAIN三种场景。

• 12小时内不允许通过移动推送远程对一台设备创建同一个activityId的实况窗。

• 对于不同的event类型，创建实况窗时，对布局类型（activityData.notificationData.type）和必填字段，有以下场景约束：

• 对于不同的布局类型（activityData.notificationData.type），需要在支持携带占位符的字段中填入至少一次status的占位符{{status}}；如果该event下keywords字段也必填，则也需要在支持携带占位符的字段中填入至少一次相应的占位符，占位符具体请参见keywords字段描述。

• 通过移动推送远程创建的实况窗，在更新时必须同时满足status和keywords要求。通过Live View Kit（实况窗服务）创建的实况窗，在移动推送远程更新时可以不填写status和keywords字段，若开发者选择填写则需满足status和keywords要求。

问题排查

创建实况窗失败

1. 检查是否已在AppGallery Connect中申请对应场景实况窗权限。

2. 检查设备是否支持实况窗，可参考构建本地实况窗调用liveViewManager.isLiveViewEnabled()方法检查。

3. 检查是否触发频率限制。

4. 对于使用移动推送远程创建的实况窗，检查是否触发远程创建实况窗限制。

5. 根据消息ID与设备ID在移动推送控制台的排查工具->排查消息页面检查实况窗推送链路。

更新/结束实况窗失败

1. 检查HarmonyLiveViewPayload参数中的activityId是否与创建实况窗时的相同。

2. 检查HarmonyLiveViewPayload参数中的version是否正确设置。

3. 检查是否触发频率限制。

4. 根据消息ID与设备ID在移动推送控制台的排查工具->排查消息页面检查实况窗推送链路。

实况窗样式异常

1. 检查HarmonyLiveViewPayload参数中的type是否匹配对应模板。

2. 检查资源文件路径是否正确