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

场景介绍

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

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

实时活动有明显的起终点

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

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

实时活动的时效性

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

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

实时活动的连续性

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

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

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

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

服务动态场景准入原则

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

服务动态场景模板

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

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

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

接入指导

[h2]开通推送服务

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

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

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

推送消息长度与数量限制

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

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

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

[h2]明确服务场景

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

[h2]申请权益

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

[h2]明确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等行为，请合理使用组件。

[h2]激活卡片

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

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

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

[h2]更新卡片状态

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

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

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

[h2]推送服务动态消息的消息体

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

// Request URL
POST https://push-api.cloud.huawei.com/v1/[projectId]/service_timeline/send
 
// Request Header
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****      
 
// Request Body
{
    "appId": "5**********7",
    "toOpenId": "A**********O",
    "sceneId": "10001",
    "subSceneId": "100010001",
    "code": "3**********7",
    "content": {
        "status": 3,
        "expireTime": 60,
        "orderTime": 1716191520,
        "amount": "¥ 18.00",
        "productCount": 1,
        "productName": "霸气芒果",
        "productImg": "image_test_1",
        "merchantName": "威**********店",
        "pickupNumber": "1668",
        "pickupTime": "16:08",
        "remainOrders": "5单/共5杯",
        "waitTime": "10-20分钟",
        "button": {
            "type": 0,
            "text": "取餐码",
            "data": {
             "testKey":"testValue"  
            }    
        },
        "clickAction": {
            "type": 0,
            "data": {
             "testKey":"testValue"  
            }    
        },
        "appendButtons": [
            "type": 0,
            "text": "取餐码",
            "data": {
             "testKey":"testValue"  
            }   
        ]
    }
}
       
       

点击消息动作

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

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

1. 发送消息时，在clickAction中携带data字段并设置type字段为0：

   // Request URL
   POST https://push-api.cloud.huawei.com/v1/[projectId]/service_timeline/send
    
   // Request Header
   Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****      
    
   // Request Body
   {
       "appId": "5**********7",
       "toOpenId": "A**********O",
       "sceneId": "10001",
       "subSceneId": "100010001",
       "code": "3**********7",
       "content": {
           "status": 3,
           "expireTime": 60,
           "orderTime": 1716191520,
           "amount": "¥ 18.00",
           "productCount": 1,
           "productName": "霸气芒果",
           "productImg": "image_test_1",
           "merchantName": "威**********店",
           "pickupNumber": "1668",
           "pickupTime": "16:08",
           "remainOrders": "5单/共5杯",
           "waitTime": "10-20分钟",
           "button": {
               "type": 0,
               "text": "取餐码",
               "data": {
                "testKey":"testValue"  
               }    
           },
           "clickAction": {
               "type": 0,
               "data": {
                "testKey":"testValue"  
               }    
           },
           "appendButtons": [
               "type": 0,
               "text": "取餐码",
               "data": {
                "testKey":"testValue"  
               }   
           ]
       }
   }
   

   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()方法中覆写如下代码：

   import { UIAbility, Want } from '@kit.AbilityKit';
   import { hilog } from '@kit.PerformanceAnalysisKit';
   
   export default class MainAbility extends UIAbility {
     onCreate(want: Want): void {
       // 获取消息中传递的data数据
       const data = want.parameters;
       hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
       // 根据实际业务场景对data进行处理
     }
   }

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

   import { UIAbility, Want } from '@kit.AbilityKit';
   import { hilog } from '@kit.PerformanceAnalysisKit';
   
   export default class MainAbility extends UIAbility {
     onNewWant(want: Want): void {
       // 获取消息中传递的data数据
       const data = want.parameters;
       hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
       // 根据实际业务场景对data进行处理
     }
   }

   

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

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

   示例如下：

   {
     "clickAction": {
     "actionType": 0,
     "data": {
   "ascfPara": {
     "path" : "pages/index?key1=value1&key2=value2" // 指定携带数据{'key1'：'value1', 'key2'：'value2'}跳转到pages/index页面
   }      
     }
   }
   }
   

   元服务获取启动参数：

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

   App({
     onLaunch(options) {      
       let path = options.path;       // 例如：pages/index
       let data = options.query;      // 例如：{'key1'：'value1', 'key2'：'value2'}
       console.info('data = ', data);
       console.info('path = ', path);
     }
     
     onShow(options) {      
       let path = options.path;       // 例如：pages/index
       let data = options.query;      // 例如：{'key1'：'value1', 'key2'：'value2'}
       console.info('data = ', data);
       console.info('path = ', path);
     }
   });
    
   Page({
              onLoad(query)
   {      
         console.info('query = ', query);  // 例如：{'key1'：'value1', 'key2'：'value2'}
   }
   });

申请权益

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以获取更多帮助。