输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档
指南
API
开放能力API

推送实况窗消息

更新时间: 2026-08-29 09:41
本文导读

场景介绍

实况窗是一种帮助用户聚焦正在进行的任务，方便快速查看和即时处理的通知形态。有关实况窗简介、权限申请、开放场景、设计规范等说明，请参见Live View Kit简介。

通过Push Kit发送的实况窗消息支持三种操作类型，分别是：

  • 创建实况窗：仅部分场景支持通过Push Kit创建实况窗，详情请参见通过Push Kit创建和更新实况窗的约束限制；其他场景请通过Live View Kit本地创建。

  • 更新实况窗：所有场景皆支持通过Push Kit更新实况窗。

  • 结束实况窗：所有场景皆支持通过Push Kit结束实况窗。

有关场景类型的详细说明请参见支持的范围与场景。

根据创建实况窗的方式不同，通过Push Kit发送实况窗消息的流程有所区别。

通过Live View Kit创建实况窗，Push Kit更新与结束实况窗

  1. 使用Push Kit，获取Push Token。

  2. 使用Live View Kit创建实况窗成功后，开发者需要将实况窗id、pushToken、实况窗场景event以及业务服务的相关的状态属性保存到业务服务端。

  3. 当业务服务的用户订单状态发生变化时，通过Push Kit通道推送更新消息，更新/结束实况窗。

通过Push Kit创建、更新、结束实况窗

  1. 使用Push Kit，获取Push Token。

  2. 将Push Token保存到业务的服务端。

  3. 通过Push Kit推送创建/更新/结束实况窗消息。

实况窗更新效果示例图：

说明

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

  • 为了确保用户看到内容的时效性，请您确保对实况窗内容进行及时更新。系统将在实况窗超过2小时未更新时，隐藏实况窗在状态栏胶囊和锁屏的展示，保留通知中心展示；超过4小时未更新，系统会认为实况窗结束，并从各个展示入口清除该实况窗。

约束与限制

推送实况窗消息能力支持Phone、Tablet设备，并且从26.0.0版本开始，新增支持Wearable设备。

部分特性在Wearable设备中存在差异，详情请参考LiveViewPayload 实况窗消息相关字段描述。

开通权益

推送实况窗消息前您需要开通对应的场景权益，可参见开通实况窗权益完成权益的申请。

说明

必须要开通实况窗权益才可以通过Push Kit推送实况窗消息，无法通过添加白名单设备的方式进行调试。

频控规则

调测阶段，每个项目每日全网最多可推送1000条测试消息。发送测试消息需设置testMessage为true。

正式发布阶段，单设备单应用下每日推送消息总条数受设备消息频控限制，系统会根据使用场景和流量进行管控，不合理的使用场景系统会进行频控。

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

开发步骤

  1. 参见指导获取Push Token。

  2. 根据应用情况选择创建实况窗的方式：

    • 通过Live View Kit创建本地实况窗，详细内容请参见构建本地实况窗。

    • 通过Push Kit远程创建实况窗，需满足创建实况窗约束。以出行打车场景为例，消息示例如下：

      收起
      自动换行
      深色代码主题
      复制
      1. // Request URL
      2. POST "https://push-api.cloud.huawei.com/v3/[projectId]/messages:send"
      3.  
      4. // Request Header
      5. Content-Type: application/json
      6. Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
      7. push-type: 7
      8. 

      9. // Request Body
      10. {
      11.   "payload": {
      12.     "activityId": 1,
      13.     "operation": 0,
      14.     "event": "TAXI",
      15.     "status": "DRIVER_ON_THE_WAY", // 司机正在赶来
      16.     "activityData": {
      17.       "notificationData": {
      18.         "type": 3,
      19.         "contentTitle": "{{status}}", // 司机正在赶来
      20.         "contentText": [
      21.           {
      22.             "text": "距您"
      23.           },
      24.           {
      25.             "text": "1.2公里",
      26.             "foregroundColor": "#FF317AF7"
      27.           },
      28.           {
      29.             "text": " | "
      30.           },
      31.           {
      32.             "text": "5分钟",
      33.             "foregroundColor": "#FF317AF7"
      34.           }
      35.         ],
      36.         "clickAction": {
      37.           "actionType": 1, // 打开应用自定义页面
      38.           "action": "xxxxxx" // 应用内置页面ability对应的action
      39.         },
      40.         "richProgress": {
      41.           "type": 0,
      42.           "nodeIcons": ["icon1.png", "icon2.png", "icon3.png"], // 取值为“/resources/rawfile”路径下的文件名
      43.           "indicatorIcon": "taxi.png", // 取值为“/resources/rawfile”路径下的文件名
      44.           "progress": 40,
      45.           "indicatorType": 1,
      46.           "color": "#FF317AF7",
      47.           "bgColor": "#19000000"
      48.         },
      49.         "extend": {
      50.           "type": 3,
      51.           "image": "phone.png", // 取值为“/resources/rawfile”路径下的文件名
      52.           "imageUrl": "https://www.xxx.com:8080/push/test", // 优先展示，如果图片无法显示则展示image的图片内容。传入图片的大小不超过512KB。从26.0.0版本开始支持此字段
      53.           "clickAction": {
      54.             "actionType": 0 // 点击辅助区打开应用首页
      55.           }
      56.         }
      57.       },
      58.       "capsuleData": {
      59.         "type": 1,
      60.         "status": 1,
      61.         "icon": "icon.png", // 取值为“/resources/rawfile”路径下的文件名
      62.         "bgColor": "#FF317AF7",
      63.         "remind": "EXPAND",
      64.         "title": "接驾中",
      65.         "content": "预计5分钟"
      66.       }
      67.     }
      68.   },
      69.   "pushOptions": {
      70.     "ttl": 1000,
      71.     "biTag": "biTag"
      72.   },
      73.   "target": {
      74.     "token": [
      75.       "MAAALgE4G98BAAAAst************jq"
      76.     ]
      77.   }
      78. }
      • [projectId]：项目ID，登录AppGallery Connect网站，选择“开发与服务”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取。
      • Authorization：JWT格式字符串，可参见Authorization获取。
      • push-type：7表示实况窗消息场景。
      • activityId：实况活动ID。详情请参见activityId。
      • operation：实况窗通知操作类型，0表示创建实况窗。详情请参见operation。
      • event：实况窗消息具体场景类型，需要与应用实际申请通过的场景一致。例如：TAXI（出行打车）、FLIGHT（航班）等。当通过Push Kit创建实况窗消息时，event取值仅支持部分业务场景，详情请参考通过Push Kit创建和更新实况窗的约束限制。
      • status：表示实况窗消息状态。operation为0时必填，取值范围根据场景类型而定，详情见Status取值范围，并且需要在支持携带占位符的字段填入至少一次status的占位符{{status}}，Push Kit将替换占位符{{status}}为Status取值范围中对应的值。
      • activityData：填写您项目中的实况窗数据。详情请参见activityData。
      • type：实况窗布局类型，有进度可视化类、强调文本类等。创建实况窗时每种event仅可使用特定的布局类型，详情请参见创建实况窗约束。
      • token：Push Token，可参见获取Push Token获取。

  3. 当用户的服务订单状态发生变化时，开发者可以调用Push Kit服务端开放的REST API服务接口，更新或者结束实况窗。

    消息详情可参见场景化消息API接口功能介绍。（若开发者更新的实况窗为通过Push Kit远程创建的实况窗，更新时请遵守创建实况窗约束）

    收起
    自动换行
    深色代码主题
    复制
    1. // Request URL
    2. POST "https://push-api.cloud.huawei.com/v3/[projectId]/messages:send"
    3.  
    4. // Request Header
    5. Content-Type: application/json
    6. Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
    7. push-type: 7
    8.  
    9. // Request Body
    10. {
    11.   "payload": {
    12.     "activityId": 1,
    13.     "operation": 1,
    14.     "event": "TAXI",
    15.     "status": "HEADING_TO_DESTINATION", // 正在去往目的地
    16.     "version": 1,
    17.     "activityData": {
    18.       "notificationData": {
    19.         "type": 3,
    20.         "contentTitle": "{{status}}", // 正在去往目的地
    21.         "contentText": [
    22.           {
    23.             "text": "距目的地"
    24.           },
    25.           {
    26.             "text": "7.2公里",
    27.             "foregroundColor": "#FF317AF7"
    28.           },
    29.           {
    30.             "text": " | 预计"
    31.           },
    32.           {
    33.             "text": "27分钟",
    34.             "foregroundColor": "#FF317AF7"
    35.           }
    36.         ],
    37.         "clickAction": {
    38.           "actionType": 1, // 打开应用自定义页面
    39.           "action": "xxxxxx" // 应用内置页面ability对应的action
    40.         },
    41.         "richProgress": {
    42.           "type": 0,
    43.           "nodeIcons": ["icon1.png", "icon2.png", "icon3.png"], // 取值为“/resources/rawfile”路径下的文件名
    44.           "indicatorIcon": "taxi.png", // 取值为“/resources/rawfile”路径下的文件名
    45.           "progress": 70,
    46.           "indicatorType": 1,
    47.           "color": "#FF317AF7",
    48.           "bgColor": "#19000000"
    49.         },
    50.         "extend": {
    51.           "type": 0
    52.         }
    53.       },
    54.       "capsuleData": {
    55.         "type": 1,
    56.         "status": 1,
    57.         "icon": "icon.png", // 取值为“/resources/rawfile”路径下的文件名
    58.         "bgColor": "#FF317AF7",
    59.         "title": "27分钟",
    60.         "content": "距目的地7.2公里"
    61.       }
    62.     }
    63.   },
    64.   "pushOptions": {
    65.     "ttl": 1000,
    66.     "biTag": "biTag"
    67.   },
    68.   "target": {
    69.     "token": [
    70.       "MAMzLg**********lPW"
    71.     ]
    72.   }
    73. }
    • [projectId]：项目ID，登录AppGallery Connect网站，选择“开发与服务”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取。
    • Authorization：JWT格式字符串，可参见Authorization获取。
    • push-type：7表示实况窗消息场景。
    • activityId：实况活动ID。详情请参见activityId。
    • operation：实况窗通知操作类型，0表示创建实况窗，1表示更新实况窗，2表示结束实况窗。详情请参见operation。
    • event：实况窗通知具体场景类型，需要与应用实际申请通过的场景一致。例如：TAXI（出行打车）、FLIGHT（航班）等。详情请参见event。
    • status：表示实况窗消息状态。operation为1且更新的实况窗为通过Push Kit远程创建的实况窗时必填，取值范围根据场景类型而定，详情见Status取值范围，并且需要在支持携带占位符的字段填入至少一次status的占位符{{status}}，Push Kit将替换占位符{{status}}为Status取值范围中对应的值。
    • version：更新实况窗通知的版本号。详情请参见version。
    • activityData：填写您项目中的实况窗数据。详情请参见activityData。
    • type：实况窗布局类型，有进度可视化类、强调文本类等。详情请参见type。
    • token：Push Token，可参见获取Push Token获取。
      说明

      若发送的activityId对应的实况窗不存在（更新或结束实况窗的场景中），将限制使用该activityId发送实况窗消息24小时。

简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 开发与测试 开放能力API 中进行搜索
请输入您想要搜索的关键词