tencent cloud

腾讯云超级应用服务

文档腾讯云超级应用服务实践教程小程序订阅消息实践教程

小程序订阅消息实践教程

PDF
聚焦模式
字号
最后更新时间： 2026-01-05 11:51:14

前言

消息能力是小程序能力中的重要组成，superapp 通过为小程序开发者提供订阅消息能力，以便实现小程序内的服务闭环，带给 superapp 用户更优的体验。在 superapp 的业务生态中，大部分的生活服务类小程序或游戏都会伴随支付行为，一旦产生支付行为就意味着会产生订单，而订单是有状态变化的，因此，需要通过消息订阅和通知的能力，及时将小程序内的订单状态变化推送给 superapp 的用户，以便用户可以实时接收到来自不同小程序内的业务通知。小程序订阅消息实现方案即是为此而生，针对上述场景，您可通过以下方案来实现订阅消息功能：

订阅消息方案

1. 前提条件

为实现 superapp 和小程序的订阅消息功能，您的 superapp 需要开通推送服务，否则小程序订阅消息无法通过 superapp 的推送渠道触达用户。

2. 添加消息模板

小程序开发者需要在控制台-小程序管理-订阅消息，从公共模板库中选择适用的消息模板，配置推送的字段后，添加为“我的模板”。
详情请参考 小程序管理-订阅消息。

3. 小程序实现订阅消息触发

第1步：获取模板 ID

按照上面描述 添加消息模板 后，可以获取到已经配置的模板 ID，用于后续消息订阅操作。

第2步：获取下发权限

在小程序中一次性订阅消息或者长期订阅消息通过 wx.requestSubscribeMessage 调起客户端订阅消息界面，用户操作后返回用户订阅消息的操作结果，结果为accept时表示用户同意订阅模板 ID 对应的模板消息且模板可用。



示例代码
JAVASCRIPT
Page({
    // tmplIds：Array of template IDs that need to be subscribed
    requestSubscribeMessage(tmplIds) {
          wx.requestSubscribeMessage({
               tmplIds,
               success: (res) => {
                    console.log('wx.requestSubscribeMessage===success', res)
                    const keysWithAccept = Object.entries(res)
                    .filter(([key, value]) => value === "accept")
                    .map(([key]) => key);
                    if (keysWithAccept.length > 0) {
                         // Send subscription message
                         this.orderSubscribe(keysWithAccept)
                    } else {
                         wx.showModal({
                              title: 'No available message templates',
                              confirmText: 'Confirm',
                              showCancel: false
                         })
                    }
               },
               fail: (res) => {
                    console.log('wx.requestSubscribeMessage===fail', res)
                    wx.showModal({
                         title: 'wx.requestSubscribeMessage fail',
                         confirmText: 'Confirm',
                         content: `${res.errMsg}【${res.errCode}】`,
                         showCancel: false
                    })
               }
          })
     },
})

第3步：调用接口下发订阅消息

当用户在小程序中触发了需要接收消息的操作后，小程序通过自定义接口调用小程序后端服务并传递可用的模板 ID，再由小程序后端服务调用平台 OpenServer提供的 send 接口发送订阅消息。

4.小程序后台下发订阅消息

适配小程序发送订阅消息的前提是小程序需要接入 getAccessToken 接口。
通常情况下，小程序后台需要获取小程序的订阅关系，如上图 orderSubscribe接口，小程序后台需要将用户订阅成功的模板、订阅时间、订阅者(openid) 持久化。一般情况下订阅消息这个动作完成以后，发消息的动作是一个未来行为；小程序后台需要根据自身的需求提供一个消息发送的平台，或者通过其它中间件、接口去触发消息发送。
这里小程序订阅消息的时候入参 tmplIds 可以通过 后台接口 去校验模板 ID 的有效性 。
目前后台发送订阅消息的接口请参考如下 接口，需要特别注意 data 字段的格式， 下面给出参考示例。
如果订阅消息模板如下：
name: {{name01.DATA}}
amount: {{amount01.DATA}}
journey: {{thing01.DATA}}
date: {{date01.DATA}}
对应的发送消息的 data 数据结构如下：
{
  "touser": "OPENID",
  "template_id": "TEMPLATE_ID",
  "page": "index",
  "data": {
      "name01": {
          "value": "who "
      },
      "amount01": {
          "value": "$100"
      },
      "thing01": {
          "value": "from beijing to shanghai"
      } ,
      "date01": {
          "value": "2018-01-01"
      }
  }
}

5. Superapp 接收并展示订阅消息




在上一个步骤中，小程序后台通过 SAS 平台向 superapp 后台推送订阅消息，superapp 需要通过 接收订阅消息 接口接收消息并完成后续自定义业务逻辑。 通常 superapp 后台需要向 superapp 提供一个拉取消息列表的接口，以便让 superapp 可以获取到从小程序推送过来的订阅消息数据，并给 superapp 的用户展示。
注意：
superapp 拉取消息列表的接口需要 superapp 后台自行开发。
以下是我们建议 superapp 接收并展示订阅消息的方式。
如果您的 superapp 具备社交聊天功能，我们建议您将订阅消息的通知入口放置在聊天列表中，方便用户实时查看。

此外，如果您的 superapp 有系统消息功能，也可以将系统消息的入口作为订阅消息的入口。

当然，您也可以根据自己的喜好来决定订阅消息的入口，我们建议将入口放置在较为显眼的位置。
有了订阅消息入口后，接下来，您需要自定义一个订阅消息列表页面，我们称呼为“消息卡片”页面，用来展示订阅消息，可以参考下方图片来实现 UI。

以下是订阅消息列表和“消息卡片”的实现方法，供参考。
进入消息卡片页面时，调用 superapp 后台拉取订阅消息。示例代码：
// 定义一个数组变量 jsonDatas，用于存储获取到的数据，初始值为 nil
BLOCK_ARRAY jsonDatas = nil;

// 调用单例 SubscriptionManager 的 getMessage 方法获取消息数据
// 参数：
//   - token: 获取登录用户 token
//   - appId: 配置文件（tcmpp-ios-configurations.json或tcmpp-android-configurations.json） 中的appKey
// 成功回调：
//   - message: 获取到的消息数据数组
// 失败回调：
//   - error: 错误信息
[SubscriptionManager.sharedInstance getMessage: UserInfo.sharedInstance.token 
                                  appId: MiniAppSDKManager.sharedInstance.configAppKey 
                                success:^(ARRAY message) {
  // 检查 message 是否为数组类型，如果不是则直接返回
  if (![message isArray]) {
    return;
  }

  // 检查 message 数组是否为空，如果为空则直接返回
  if ([message isEmpty]) {
    return;
  }

  // 将获取到的消息数据数组赋值给 jsonDatas 变量
  jsonDatas = message;

  // 创建一个可变数组 arrayDatas，用于存储解析后的数据模型
  MUTABLE_ARRAY arrayDatas = [NSMutableArray array];

  // 遍历 jsonDatas 数组
  for (DICTIONARY json in jsonDatas) {
    // 将每个 json 数据解析成 SubscribeInfoModel 模型对象
    SubscribeInfoModel *model = [[SubscribeInfoModel alloc] initWithJsonDatas: json];

    // 将模型对象添加到 arrayDatas 数组中
    [arrayDatas addObject: model];
  }

  // 将 arrayDatas 数组赋值给 self.modelDatas 属性
  self.modelDatas = [NSArray arrayWithArray: arrayDatas];

  // 在主线程上异步执行 tableView 的 reloadData 方法，刷新表格数据
  [self.tableView performSelectorOnMainThread: @selector(reloadData) 
                                   withObject: nil 
                                waitUntilDone: YES];
} 
                              failure:^(ERROR error) {
  // 处理获取消息数据失败的情况，这里可根据业务场景进行失败提示
}];
在示例代码中，我们通过 superapp 封装的 getMessage 接口，传入了用户 token 和 AppKey 参数来获取订阅卡片的数据，获取成功回调中，将对应的订阅数据进行反序列化，设置在视图容器中，最后进行刷新。
点击卡片后，可进入对应的小程序页面，示例代码：
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath{
    // 获取当前点击卡片对应的订阅模型对象
    SubscribeInfoModel *model = self.modelDatas[indexPath.row];
    // 传入订阅模型对象的参数，调用SDK的打开小程序接口
    [[TMFMiniAppSDKManager sharedInstance] startUpMiniAppWithAppID:model.MnpId verType:model.vertype scene:0 firstPage:model.Page paramsStr:nil parentVC:self completion:^(NSError * _Nullable error) {
        if(error) {
            // 打开失败，可根据业务场景进行提示
            return;
        }
        // 打开成功，可根据业务场景进行提示
    }];
}
在示例代码中，我们通过点击列表元素来获取对应的订阅对象，通过调用 startUpMiniAppWithAppID 方法，传入小程序 ID、小程序状态、小程序入口页面等参数来实现打开小程序。
上一篇: 小程序登录实践教程下一篇: 支付与商户号说明

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈