ReaderMX.
微信开发者

多端应用开发指南③：如何接入消息推送能力？

微微信团队约 7 分钟

在开发 APP 应用时，绝大部分开发者都希望为 APP 支持消息推送能力。用户在访问 APP 过程中或者离开后，可以在业务必要节点下发消息到用户设备通知栏，实现业务召回目的。

本文详细介绍，当开发者在「多端应用」开发时，如何接入并测试消息推送能力。

一、消息推送服务

在接入之前，我们需要了解消息是如何到达用户设备中的。

根据用户使用设备的不同，为该设备提供消息推送服务的推送平台也不同，一般都是设备品牌厂商自己的推送平台。

比如 Android 设备，在国内有多个厂商推送平台，分别负责对自己品牌下的手机设备下发消息通知。

开发者可以逐个对接每个推送平台，来支持向多个品牌设备中发送消息，这是比较复杂的开发工程。

除了自己去对接，开发者还可以使用「一站式推送服务」，相当于集成了多个厂商推送平台，开发者只需要简单配置就可以完成接入。

二、消息类型

当你接入一站式推送服务时，需要在 APP 中引入「推送服务」的专用模块包或插件。

当用户打开 APP 时，要使用「推送服务」提供的 AppId 和 AppKey 以及在业务过程中确定的 用户ID 来注册初始化。初始化后，该设备就与「推送服务」建立连接，一直保持 online 状态。

在 online 状态时，开发者可以调用「推送服务」的接口用约定的 用户ID 来向该设备发送推送消息，此时发送的消息类型为「在线推送」。

「在线推送」一般不依赖厂商的推送平台，是「推送服务」 模块直接在用户设备中发起，基本支持所有机型设备（即使你没有接入对应的推送平台）。

而当用户退出 APP 后，由于有过初始化注册操作，这时设备相对于「推送服务」来讲是 PushOnline 状态。开发者可以在这个状态中，调用「推送服务」的接口获取 用户ID 所注册的设备，并向对应注册的设备发送消息，此时发送的消息类型为「离线推送」。

向指定品牌机型设备发送「离线推送」消息，需要满足以下所有条件：

  1. 「一站式推送服务」支持设备所属的厂商推送平台（不同推送服务接入的厂商推送平台有差异，在接入时需要确认）

  2. 「一站式推送服务」提供的客户端推送模块支持注册该品牌设备机型。

  3. 开发者需自行注册对应推送平台，并将证书和配置信息更新到「一站式推送服务」

  4. 用户ID 对应的用户打开过 APP 并完成推送初始化，向「一站式推送服务」发送了 Token 信息（该 Token 用于厂商推送平台最终发送消息）

这里的 用户ID 是你在业务开发过程中自己确定的，「推送服务」在 APP 初始化时只会记录 用户ID，并获取设备的推送相关 Token（用于在厂商推送平台发送消息），关联发送到「推送服务」的数据库中。

后续你在使用「推送服务」的接口发送消息时，需提供 用户ID，「推送服务」会拿出其关联的 Token（如果你在多个设备中关联了一个用户ID，则会有很多），向厂商推送平台发送正式的消息推送请求。

三、接入步骤

「多端应用」支持腾讯云「即时通信 IM 推送服务」，接下来我们以 iOS 设备举例，演示从配置到测试的整个流程。

3.1 在腾讯云即时通信 IM 控制台，创建应用

在应用管理中，点击「创建新应用」按钮，按照页面提示创建应用，具体可查看多端文档指引。

Image

3.2 在厂商处注册账号并获取相关信息

首先要按照生成 iOS Certificate 步骤，获取 P12 证书文件（导出时需要设置密码），这里的 P12 文件用于构建 IPA 安装包，后面在厂商开发者平台的其他设置都是要关联这个 P12 文件。（我们称为打包证书）

接下来按照创建 Provisioning Profile 步骤，在厂商开发者平台创建 appID。

需要注意在 capabilities 选择上，要勾选 Push Notifications（下面的 Broadcast Capability 是广播能力，可向所有注册者发消息，该能力不在本文中体现，可按需勾选），勾选后点击后面的「Configure」按钮，配置推送证书。（这里推荐直接配置 Production SSL Certificate）

Image

下载的证书格式为 ser，需要导出为 P12 文件并设置密码。（我们称为推送证书）

3.3 将厂商信息配置到「推送服务」的接入设置

我们直接将上一步的推送证书配置到控制台，配置类型选 P12。

如果你的推送证书为 Production SSL Certificate，在配置面板的「证书类型」选择上需要注意区分：

  1. 开发环境： APP 是在微信开发者工具中直接预览安装到手机中的。

  2. 生产环境： 微信开发者工具打包构建了正式版 IPA 安装包，并通过测试渠道或应用商店安装在手机中。

如果推送证书为 Development SSL Certificate，则只选择 开发环境。

Image

配置完毕后，记录 证书 ID，以及控制台右侧的 SDKAppID 和 客户端密钥，用于后续步骤

3.4 编写代码，完成消息推送初始化

在微信开发者工具中打开你的「多端应用」项目，在根目录中打开终端，执行如下命令

npm i @tencentcloud/donut-push

如果本机没有 npm 需要安装 nodejs

然后在微信开发者工具菜单栏，点击「工具-构建 npm」，工具会编译 donut-push ，产物放在 miniprogram_npm 目录中。

然后在 app.js 中引入以下代码：

import Push from "@tencentcloud/donut-push"
App({
  onLaunch: function () {
    this.registerPush = registerPush
  }
})
function registerPush(userid = '', callback = () => {}) {
  // 这里的配置可以用服务端动态下发，尽量不要直接写在前端
  const sdkAppID = 0; // 消息推送 SDKAppID
  const appKey = ''; // 消息推送 客户端密钥
  return new Promise((resolve) => {
    Push.setRegistrationID(userid)
      .then((res) => {
        console.info("设置注册用户ID", res);
        return Push.registerPush(sdkAppID, appKey);
      }).then((res) => {
        console.info("注册推送服务", res);
        return Push.getRegistrationID();
      }).then((res) => {
        console.info("完成注册", res);
        resolve(true)
      })
      .catch((e) => {
        console.error("注册失败", e);
        resolve(true)
      });
    Push.addPushListener(Push.EventName.ON_NOTIFICATION_CLICKED, );
  })
}

在业务过程中，确定要注册推送时，传入用户 ID ，发起推送注册。

const userid = 'zirali' // 这是你确定的用户ID，可以在登录后或者使用本地生成的 UUID，取决于你的业务场景
this.registerPush(userid, (param) => {
  // 这是在线推送时监听方法，离线推送时 APP 没有运行，因此不需要监听
  console.log('收到消息', JSON.stringify(param));
})

3.5 在 app.miniapp.json 文件中配置消息推送的信息

在 iOS 配置集中「消息推送」，勾选开启消息推送，然后配置插件版本号，当前最新 8.3.1，如果版本过旧，运行时会有 console 提醒。

然后 businessID 中，配置消息推送控制台中记录的证书 ID 数字。

Image

在官方插件配置集中，iOS 插件配置插件，插件 ID 为 wxext14566970e7e9f62

Image

3.6 预览运行

直接连接手机，使用 3.2 步骤获取的打包证书，将 APP 安装到手机中。正常情况下，在 registerPush 执行后，console 会提示"完成注册"。

如果提示的是"注册失败"，则需要看后面的详细报错，一般有两个情况：

  1. 厂商开发者平台里，配置 AppID 中缺少一些能力，注意要勾选 Push Notifications，并配置推送证书。否则会提示 未找到应用程序的“aps-environment”的权利字符串，如果配置了仍然报此错误，需要在关联的 Profile中重新下载 mobileprovision 文件，并在打包 APP 时用新的 mobileprovision。

  2. 插件或者 businessID 没有配置正确，一般会体现在报错中。

3.7 在推送服务控制台测试消息发送

在推送服务控制台中，点击左侧的「接入测试」，输入用户名进行「在线推送」和「离线推送」的测试。

Image

「在线推送」测试需要在 APP 正在运行时发起，否则推送失败。

「离线推送」只要注册过且可以获取 token，都可以发送，但 APP 正在运行时，设备不会收到消息，测试仍然显示成功。（不同的厂商推送平台这里的逻辑略有差异，需要实际测试体验）

如果「离线推送」时，提示失败且跟开发、正式证书相关，一般就是推送证书类型配置错了，重新配置一下即可。

以下是「在线推送」和「离线推送」的测试效果。

Image

四、服务端推送消息

测试完成后，在后端服务中需要接入 API，用于在相应业务节点向指定用户或指定标签群体发送消息。

我们以简单的单发推送（向指定用户发送消息）举例：

比如推送应用所在地为中国，对应的发送示例如下：

`https://console.tim.qq.com/v4/timpush/batch?usersig=${用户签名}&identifier=${管理员账号}&sdkappid=${应用的appid}&random=${32位随机数}&contenttype=json`

请求包体如下：

{
  "From_Account": "administrator", // 消息推送方账号（支持指定为任意存在的账号）
  "To_Account": ["user1","user2"], // 消息接收方用户 UserID，1-500个
  "MsgRandom": 3674128, // 消息随机数（32位无符号整数），后台用于同一秒内的消息去重，需确保随机。
  "OfflinePushInfo": {
      "PushFlag": 0,  // 0-离线推送，1-在线推送
      "Title": "推送标题",
      "Desc": "推送内容"
  }
}

具体可以参考腾讯云文档：https://cloud.tencent.com/document/product/269/108906

五、轻松入门学习

你在开发多端应用，遇到一些理解误区或问题瓶颈时，推荐学习微信团队推出的《多端应用开发系列课程》。

我们会根据产品能力演进及其更新和预告课程内容，如果你想深入小程序多端框架开发实践，欢迎持续学习本系列课程！

KEEP THE THREAD GOING

更多来源文章