输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
我的
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
开发与测试
您当前正在浏览新版开发者文档中心，目录分类和层级有所调整。点击左侧当前文档分类名称前的“☰”图标，可切换文档分类。 了解新版目录
开发与测试元服务开发元服务指南ArkTS开发元服务元服务开发指导经营履约能力开发推送推送基于账号的服务动态消息

推送基于账号的服务动态消息

更新时间: 2026-10-19 11:26
复制页面
本文导读
展开章节

场景介绍

服务动态消息是提供给开发者的B2C（Business-to-Customer）消息能力，通过服务动态消息，开发者可以基于华为支付订单号或用户前端场景化button获取到的code，向用户推送关键节点的动态消息，及时提醒用户订单进度，帮助用户聚焦正在进行的任务，方便快速查看和即时处理的通知形态。

服务动态消息具有一定特点，具体如下：

实时活动有明显的起终点

该事件或服务需要持续一段时间，有明确的开始和结束，而非单点的提醒或信息。

例：打车、外卖等从事件开始到结束需要经历一段时间；单点提醒，则不适用。

实时活动的时效性

该内容为正在进行或即时发生的事件或服务的提醒，在特定时间段内，及时提供给用户有价值的信息。

例：打车行程中、外卖配送中等正在进行的用户活动；2天后的机票，在刚买时不提醒，而在出发前提示，具体提醒时间根据业务实际情况确定。

实时活动的连续性

服务动态所展示的内容需要根据事件状态变动更新，以确保用户看到最新的状态。

例：打车场景中，会基于司乘状态变化而呈现呼叫车辆中、司机接驾中、司机到达上车点、前往目的地中、待支付、已支付等状态。而优惠券过期提醒，话费充值提醒不具备变化性，不属于服务动态消息。

在展示形态上，服务动态支持在通知中心、锁屏、状态栏、负一屏等位置展示，主要有两种展示形式：胶囊态（在状态栏显示胶囊状态，点击状态栏胶囊后可展开为悬浮卡片）和卡片态。

效果图如下，真实样式请以实际效果为准：

表1 状态效果图
展开

通知中心

锁屏

状态栏

负一屏状态机

负一屏消息盒子

胶囊状态：

悬浮卡片：

服务动态场景准入原则

  • 服务动态是用户非常关注，且需要反复查看或快捷操作的场景和活动。
  • 活动本身具有明显的开始和结束时间，也代表着该活动的进行是有时限的。
  • 用户对接收到该活动的通知有明确的预期，通常为用户主动行为触发，而非一些信息推荐。
  • 需要确保展示内容对用户有足够的价值，不可用于营销、广告场景。

服务动态场景模板

场景模板有对应的类目要求，符合类目要求的元服务才可以申请使用相应的场景模板（场景模板 配置参数请见服务动态参数说明示例说明）。

以下为部分常用场景模板示例，供开发者参考。如需更多场景支持，可通过邮箱atomicservice@huawei.com 与我们联系。

点击表格中的任一场景，即可下载对应的接口文档：

展开

场景标识sceneId

场景名称

子场景标识subSceneId

子场景名称

适用类目

Code获取方式

10001

外卖

100010001

外卖-自取

获取外卖与自取订单状态的实时提醒

华为支付订单号

100010002

外卖-配送

华为支付订单号

100010003

外卖-配送（进度可视型）

华为支付订单号

100010004

外卖-自取（进度可视型）

华为支付订单号

10002

停车

100020002

停车缴费

获取停车时间与停车费在线查缴的提醒

/

10003

酒店民宿入住

100030001

酒店民宿入住

根据酒店预订信息，提供入住提醒

华为支付订单号

10005

取号排队

100050001

排队取号

实时呈现排队状态及取号提醒
  • 华为支付订单号
  • 通过前端场景化button获取

100050002

挂号就诊
  • 华为支付订单号
  • 通过前端场景化button获取

100050003

排队就餐
  • 华为支付订单号
  • 通过前端场景化button获取

10011

景区预约

100110001

景区预约

实时呈现景区动态和游玩提醒

华为支付订单号

10018

演出提醒

100180001

演出提醒

实时推送演出动态和观演提醒

华为支付订单号

10019

景区小交通

100190001

景区小交通

实时推送景区小交通相关提醒

华为支付订单号

10021

打车出行

100210001

打车出行

实时呈现打车、代驾状态提醒
  • 华为支付订单号
  • 通过前端场景化button获取
  

代驾出行

10021000

代驾出行
  • 华为支付订单号
  • 通过前端场景化button获取

10022

打卡

100220001

打卡路线

旅游-旅游/行程助手/旅游攻略/行程记录

华为支付订单号

10023

预约参观

100230001

展馆预约

获取线上预约和使用状态提醒
  • 华为支付订单号
  • 通过前端场景化button获取

10038

同城即时闪送

100380001

同城即时闪送

展示同城即时闪送订单的实时配送进度

l 华为支付订单号

通过前端场景化button获取

10039

赛事实况

100390001

赛事实况

可查看赛事比赛得分/进展等...

l 华为支付订单号

通过前端场景化button获取

接入指导

开通推送服务

1. 查看登录AppGallery Connect网站，选择“我的项目”。

2. 在项目列表中找到您的项目，在项目下的应用列表中选择需要配置推送服务参数的应用。

3. 在左侧导航栏选择“增长 > 推送服务”，点击“立即开通”，在弹出的提示框中点击“确定”。至此，您已开通推送服务。

推送消息长度与数量限制

消息体最大不能超过4096Bytes。

消息发送量，单个元服务每天最多推送3000条消息到单个设备上。

说明

推送服务权益为项目级，若您已有开通过推送服务的项目，当您在项目中添加新的元服务时，无需再次开通推送服务。

明确服务场景

开发者首先需要明确自己的服务场景，根据对应的服务动态场景进行申请和接入。可参考服务动态场景模板查询平台开放的场景。

申请权益

开发者按照申请权益，向平台申请服务动态权益，平台运营审核通过后才可以进行接入。

明确code获取方式

该code在本次服务进程中唯一，后续开发者更新用户的服务状态均通过此code进行。

  • 将华为支付订单号作为code。

    当用户在元服务内调用华为支付收银台进行支付，开发者可获得华为支付订单号sysTransOrderNo，可直接作为code。

    注意
    • 仅支持当前元服务的华为支付订单号，请勿使用其他元服务、APP支付等来源的订单号。
    • 待支付状态下，开发者可通过商户订单号mercOrderNo查询某笔订单的支付状态。
  • 从HarmonyOS 6.0开始，支持通过前端场景化button获取code，只有符合场景要求的场景，才可以使用服务动态授权码Button获取code。

    开发者需要在前端将触发服务的button组件的 openType 的值设置为functionalButtonComponentManager.OpenType.REQUEST_SUBSCRIBE_MESSAGE。当用户点击 button 后，获取平台提供的授权码code。

    注意

    平台会对相关button组件进行规范性使用的检测，包括是否存在诱导用户点击、通过与卡片无关的按钮获取code等行为，请合理使用组件。

激活卡片

针对将华为支付订单号作为code，开发者需在支付完成后调用服务端接口send 传入初始化卡片状态与状态相关字段（参考推送服务动态消息的消息体），用以首次激活code，后续才可以继续通过send更新服务的动态。

针对通过前端场景化button获取code，开发者需要在获取后24小时内调用服务端接口send传入初始化卡片状态与状态相关字段，用以首次激活code，后续才可以继续通过send更新服务的动态。

超过24小时未激活，后续不允许使用该code创建服务动态。

更新卡片状态

code激活后，开发者可调用服务端接口send传入需更新的卡片状态与状态相关字段（参考推送服务动态消息的消息体）。卡片更新需在子场景的事件有效期内完成，超过子场景的事件有效期，或状态无可变更的下一状态时（如状态更新到“订单已完成”），不再允许开发者更新。

说明

服务动态在通知中心、锁屏、状态栏位置的卡片展示规格，需同时遵循实况窗生命周期管控规格，不符合设计规范的方案将不被予以开通服务动态正式权限。为了确保用户看到内容的时效性，请您确保对实况窗内容进行及时更新。

  • 单个实况窗的生命周期最长不超过8小时，超过8小时后，系统会认为实况窗结束。即单个事件所有的卡片状态更新需在8小时内完成。
  • 在实况窗超过2小时未更新时，系统将隐藏实况窗在状态栏胶囊和锁屏的展示，保留通知中心展示；超过4小时未更新，系统会认为实况窗结束，并从各个展示入口清除该实况窗。

推送服务动态消息的消息体

以外卖场景外卖自取子场景为例，示例如下。更多详情请见服务动态推送API接口。

收起
自动换行
深色代码主题
复制
  1. // Request URL
  2. POST https://push-api.cloud.huawei.com/v1/[projectId]/service_timeline/send
  3.  
  4. // Request Header
  5. Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****      
  6.  
  7. // Request Body
  8. {
  9.     "appId": "5**********7",
  10.     "toOpenId": "A**********O",
  11.     "sceneId": "10001",
  12.     "subSceneId": "100010001",
  13.     "code": "3**********7",
  14.     "content": {
  15.         "status": 3,
  16.         "expireTime": 60,
  17.         "orderTime": 1716191520,
  18.         "amount": "¥ 18.00",
  19.         "productCount": 1,
  20.         "productName": "霸气芒果",
  21.         "productImg": "image_test_1",
  22.         "merchantName": "威**********店",
  23.         "pickupNumber": "1668",
  24.         "pickupTime": "16:08",
  25.         "remainOrders": "5单/共5杯",
  26.         "waitTime": "10-20分钟",
  27.         "button": {
  28.             "type": 0,
  29.             "text": "取餐码",
  30.             "data": {
  31.              "testKey":"testValue"  
  32.             }    
  33.         },
  34.         "clickAction": {
  35.             "type": 0,
  36.             "data": {
  37.              "testKey":"testValue"  
  38.             }    
  39.         },
  40.         "appendButtons": [
  41.             "type": 0,
  42.             "text": "取餐码",
  43.             "data": {
  44.              "testKey":"testValue"  
  45.             }   
  46.         ]
  47.     }
  48. }
  49.        
  50.
  • [projectId]：项目ID，登录AppGallery Connect网站，选择“开发与服务”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取。
  • Authorization：JWT格式字符串，可参见Authorization获取。
  • appId：元服务的APP ID，元服务的APP ID，登录AppGallery Connect网站，选择“APP与元服务”，左侧导航栏选择“应用信息 > 基本信息”，在该页面获取。
  • toOpenId：接收者（用户）账号登录的openID。使用从端侧上报的openID，或请求华为账号服务器获取用户信息。可参考元服务账号使用规范进行华为账号登录的设计和接入。
  • sceneId：场景标识。详情请见服务动态发送场景说明。
  • subSceneId：子场景标识。详情请见服务动态发送场景说明。
  • code：授权码，用于服务动态消息推送和更新。详见明确code获取方式。
  • content：服务动态指定状态参数。服务动态消息推送必须以状态节点类型为“起始节点”状态开始推送，以“结束节点”状态结束服务动态消息。详情请见请求体结构说明。定义Button、clickAction、appendButtons点击模板卡片后的跳转页面，仅限跳转当前元服务内页面。
  • clickAction：卡片点击事件，可通过携带data字段在点击后将数据传递给元服务。详情请参考点击消息动作。
  • button：卡片按钮点击事件，可通过携带data字段在点击后将数据传递给元服务。详情请参考点击消息动作。

业务响应码报错问题请参考业务响应码。

点击消息动作

点击消息进入元服务首页或指定页并传递数据

消息示例如下，更多详情请见服务动态推送API接口。

  1. 发送消息时，在clickAction中携带data字段并设置type字段为0：
    收起
    自动换行
    深色代码主题
    复制
    1. // Request URL
    2. POST https://push-api.cloud.huawei.com/v1/[projectId]/service_timeline/send
    3.  
    4. // Request Header
    5. Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****      
    6.  
    7. // Request Body
    8. {
    9.     "appId": "5**********7",
    10.     "toOpenId": "A**********O",
    11.     "sceneId": "10001",
    12.     "subSceneId": "100010001",
    13.     "code": "3**********7",
    14.     "content": {
    15.         "status": 3,
    16.         "expireTime": 60,
    17.         "orderTime": 1716191520,
    18.         "amount": "¥ 18.00",
    19.         "productCount": 1,
    20.         "productName": "霸气芒果",
    21.         "productImg": "image_test_1",
    22.         "merchantName": "威**********店",
    23.         "pickupNumber": "1668",
    24.         "pickupTime": "16:08",
    25.         "remainOrders": "5单/共5杯",
    26.         "waitTime": "10-20分钟",
    27.         "button": {
    28.             "type": 0,
    29.             "text": "取餐码",
    30.             "data": {
    31.              "testKey":"testValue"  
    32.             }    
    33.         },
    34.         "clickAction": {
    35.             "type": 0,
    36.             "data": {
    37.              "testKey":"testValue"  
    38.             }    
    39.         },
    40.         "appendButtons": [
    41.             "type": 0,
    42.             "text": "取餐码",
    43.             "data": {
    44.              "testKey":"testValue"  
    45.             }   
    46.         ]
    47.     }
    48. }
    49.
    1. type：点击消息的动作，0表示点击消息后默认进入首页。

      支持通过指定 data 参数跳转至该元服务内指定页面，详情请见调用方UIAbility指定启动页面。

    2. data：点击消息时携带的JSON格式的数据，必须是key-value格式，最大长度1024字节。示例：{"key1": "value1", "key2": "value2"}
  2. data数据获取：点击消息首次进入元服务页面时，需在onCreate()方法中获取消息data数据；当元服务进程存在时，需在onNewWant()方法中获取消息data数据。

    在元服务首页中（通常为项目模块级别下的src/main/module.json5中mainElement的值）的onCreate()方法中覆写如下代码：

    收起
    自动换行
    深色代码主题
    复制
    1. import { UIAbility, Want } from '@kit.AbilityKit';
    2. import { hilog } from '@kit.PerformanceAnalysisKit';
    3. 

    4. export default class MainAbility extends UIAbility {
    5.   onCreate(want: Want): void {
    6.     // 获取消息中传递的data数据
    7.     const data = want.parameters;
    8.     hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
    9.     // 根据实际业务场景对data进行处理
    10.   }
    11. }

    onNewWant()方法中覆写如下代码：

    收起
    自动换行
    深色代码主题
    复制
    1. import { UIAbility, Want } from '@kit.AbilityKit';
    2. import { hilog } from '@kit.PerformanceAnalysisKit';
    3. 

    4. export default class MainAbility extends UIAbility {
    5.   onNewWant(want: Want): void {
    6.     // 获取消息中传递的data数据
    7.     const data = want.parameters;
    8.     hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
    9.     // 根据实际业务场景对data进行处理
    10.   }
    11. }
    注意

    onNewWant()方法仅在单例（singleton）模式下可用。

  3. 对于ascf框架开发的元服务，可通过clickAction中的data传入启动参数，内容需为{ ascfPara: [key: string]: Object }结构，详情请见want参数解析。

    示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. {
    2.   "clickAction": {
    3.   "actionType": 0,
    4.   "data": {
    5. "ascfPara": {
    6.   "path" : "pages/index?key1=value1&key2=value2" // 指定携带数据{'key1'：'value1', 'key2'：'value2'}跳转到pages/index页面
    7. }      
    8.   }
    9. }
    10. }
    11.

    元服务获取启动参数：

    可以在ASCF元服务的App的onLaunch、onShow或Page的onLoad生命周期中获取传递的启动参数信息。

    收起
    自动换行
    深色代码主题
    复制
    1. App({
    2.   onLaunch(options) {      
    3.     let path = options.path;       // 例如：pages/index
    4.     let data = options.query;      // 例如：{'key1'：'value1', 'key2'：'value2'}
    5.     console.info('data = ', data);
    6.     console.info('path = ', path);
    7.   }
    8.   
    9.   onShow(options) {      
    10.     let path = options.path;       // 例如：pages/index
    11.     let data = options.query;      // 例如：{'key1'：'value1', 'key2'：'value2'}
    12.     console.info('data = ', data);
    13.     console.info('path = ', path);
    14.   }
    15. });
    16.  
    17. Page({
    18.            onLoad(query)
    19. {      
    20.       console.info('query = ', query);  // 例如：{'key1'：'value1', 'key2'：'value2'}
    21. }
    22. });

申请权益

  1. 提交申请

    登录AppGallery Connect网站，选择“开发与服务”。

    在项目列表中，选择目标项目及应用。

    进入“项目设置 > 开放能力管理”页面，找到“服务动态”，点击“申请”。

    如需推送带图片的服务动态消息，请同时申请“图片资源托管”子能力（用于消息卡片右侧展示的图片资源托管）。状态效果图参见 状态效果图。

  2. 填写申请信息

    参考“申请原因”模板，提供以下必需信息：

    • 申请场景：本次申请涉及的服务动态场景
    • 使用场景：业务场景描述（说明服务用途、用户使用路径）
    • 基础信息：AGC项目ID、应用ID、应用名称、应用ClientID、应用包名
    • 联系方式：对接人邮箱、手机号码（用于后续业务对接）

    提交后，请等待运营经理审核。

  3. 申请审核

    返回“开放能力管理”页面，状态会变为“申请中”。

    运营经理将在 1~3 个工作日内 完成审核。

    审核结果将通过互动中心发送通知。若审核不通过，请根据反馈意见修改后重新提交。

  4. 审核通过 ≠ 配置完成

    审核通过仅表示您的资质通过审核，能力尚未正式开通。

    审核通过后，我们的运营经理将按您提交的联系方式与您取得联系，开展后续对接工作，包括：

    • 确认您的业务场景、状态节点与消息模板规格；
    • 确认服务动态推送的字段映射关系；
    • 确认卡片跳转逻辑、素材规范等；
    • 双方确认无误后，运营经理将在业务平台为您配置权益。

权益配置完成后，您才可正式调用服务动态能力。

说明
  • ProjectID: 项目ID，登录AppGallery Connect网站，选择“开发与服务”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取。
  • AppID：元服务的APPID，登录AppGallery Connect网站，选择“APP与元服务”，左侧导航栏选择“应用信息 > 基本信息”，在该页面获取。
  • ClientID：元服务ClientID，登录AppGallery Connect网站，选择“开发与服务”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置 > 常规 > 应用 > OAuth 2.0客户端ID（凭据）”找到应用的Client ID。
  • 如您在申请过程中有任何疑问，可通过邮箱atomicservice@huawei.com联系我们。

常见问题

如有疑问，请参阅服务动态接入FAQ以获取更多帮助。

推送基于账号的订阅消息
分享
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明