微信小程序多端框架

最近更新时间:2025-01-22 10:50:13

我的收藏

前置条件

1. 厂商配置

说明:
微信开发者工具 中开启推送服务,默认支持在线推送。如果您需要使用离线推送,请您先完成厂商配置,具体操作方法可参见 厂商配置 - 微信小程序多端框架

2.微信开发者工具 版本 ≥ 1.06.2410152 >>下载地址

集成腾讯云消息推送服务

步骤1: 推送插件配置

说明:
微信开发者工具 中开启推送服务,默认支持在线推送。
Android
iOS

插件配置

1. 在可视化界面配置填写插件版本号,勾选开启腾讯云消息推送功能

查看 更新日志 获取插件最新版本号


2. 设置 Android SDK 版本

推送服务所需的微信小程序多端框架 Android SDK 最低版本为 1.4.7,推荐使用 最新版本


插件配置

1. 在可视化界面配置填写插件版本号,勾选开启腾讯云消息推送功能

查看 更新日志 获取插件最新版本号。


2. 设置 iOS SDK 版本

推送服务所需的微信小程序多端框架 iOS SDK 版本号为 1.4.15 , 推荐使用 最新的 SDK


步骤2: 离线推送配置

说明:
如果只使用在线推送,则无需进行厂商离线推送配置。
Android
iOS

离线推送配置

可参见微信小程序多端框架官方文档 Android 配置原生资源

1. 配置 timpush-configs.json

推送服务运行时需要从配置文件读取 appid、appkey 、证书 ID 等信息,需要把相应的 timpush-configs.json 文件放到 assets 文件夹打包到 apk 中;
timpush-configs.json 文件可以从 即时通信 IM 控制台 - 推送服务 Push 直接下载:

将 timpush-configs.json 放到原生资源目录的 assets 文件夹下:


2. 配置厂商资源文件

1. 华为、荣耀、谷歌 FCM 的厂商推送,需要读取各自的配置文件,要把相应的配置文件放在 app 目录下 。
各厂商的配置文件需要分别去厂商的推送控制台下载。
注意:
不要修改厂商配置文件名称,否则厂商推送会集成失败。


3. 配置证书指纹(华为、荣耀)

华为、荣耀需要配置证书指纹才能正常收到离线推送。请参见华为证书指纹配置荣耀证书指纹配置

4. 配置离线推送消息分类

厂商推送都有消息分类机制,不同类型也会有不同的推送策略。需正确配置推送消息分类才能正常收到离线推送。

离线推送配置

1. 配置证书和描述文件

请参见 微信小程序多端框架配置文档腾讯云推送厂商配置文档 以生成 iOS 应用运行时所需的证书和 Provisioning Profile,这些文件将在后续配置中使用。您需要准备以下文件:
开发证书.p12
主 App 描述文件.mobileprovision


2. Apple Developer 平台 Bundle ID 配置

请参见 Apple Developer 平台 Bundle ID 配置指引,配置时请勾选以下能力:
Push Notification
App Group (按需配置:字段配置可参见 生成 App GroupID)
Donut 建议的权限:Access WiFi Information、Associated Domains、Hotspot、Wireless Accessory Configuration;如果使用苹果登录,还需开启 Sign In with Apple(更多其他权限开发者按需开启,并非越多越好哈)

3. 在 Donut 控制台里绑定移动应用的 Bundle ID

微信小程序多端应用控制台 里绑定移动应用的 Bundle ID ,微信开发者工具在真机运行 iOS 时需要明确 Bundle ID


4.苹果推送服务 (APNs) 证书 ID 配置:

当您需要接入 APNs 时开启厂商通道推送时,businessID必传项,请先按照 证书配置文档 上传证书到推送控制台,之后控制台会为您分配此ID。


5. 运行前准备

当您点击 Donut 运行程序运行于真机时,会出现提示框引导您使用开发证书(.p12 文件)和主应用程序的描述文件。
说明:
接入至此,您已经具备了在线推送和厂商推送的所有推送能力,已可满足绝大部分业务需求。
后续 NSE 的配置,推荐您完整测试完推送功能后按照业务需求接入。

6. NSE 功能配置 (可选)

当您希望利用 iOS 10 Service Extension 特性来设置 APNs 离线推送的通知图片或统计消息的到达率时,您需要在相应的 project.miniapp.json 文件中主动配置 NSE。同时,请确保在证书控制台中启用 mutable-content 选项,以便充分利用 iOS 10 Service Extension 的功能。
需要注意的是 NSE 是主 App 的插件,推送能力是主 App 带来的,NSE是推送服务扩展,因此常用 NSE 来做一些特性需求的。
注意:
请再次参见 微信小程序多端框架配置文档腾讯云推送厂商配置文档 以生成 NSE 的Provisioning Profile,您需要重复之前生成描述文件的步骤。区别是标识符不同,NSE 的标识符规则如下 :
Notification Service Extension (NSE) 的 Bundle ID 通常是主应用程序的 Bundle ID 后面加上扩展的标识符,生成描述文件的步骤和主 App 一致。例如:您的主 App 描述文件( BundleID 为:com.yourcompany.yourapp) 那么您的 NSE 描述文件 ( BundleID 为:com.yourcompany.yourapp.extension
您需要准备以下文件:
开发证书.p12 (之前步骤已经准备完毕)
主 App 描述文件.mobileprovision (之前步骤已经准备完毕)
Service Extension 的描述文件.mobileprovision(本次功能需要新增的描述文件)

当您准备好以上文件后,可以按照描述填入相关信息:

说明:
NSE相关配置详细描述如下:
开启 NSE :借助 iOS 10 Service Extension 特性统计消息抵达率 及设置 APNs 离线推送的通知图片。
NSE BundleID : 通常是主应用程序的 Bundle ID 后面加上扩展的标识符,生成描述文件的步骤和主 App 一致。
NSE profilePath : 开发环境下的 NSE 的Profile的文件路径,推荐放置于 project.miniapp.json 当前目录。
NSE distributeProfilePath: 发布环境下 NSE 的Profile的文件路径,推荐放置于 project.miniapp.json 当前目录。
TIMPushAppGroupID , 当您需要使用 TIMPush 组件统计推送抵达率时,推荐您按照配置文档配置。
请您按照情况填写。

推送服务使用

集成 JS API

说明:
如何使用 npm 请查阅官方文档,此处不再赘述。
1. 在 miniprogram 目录下执行如下命令安装 @tencentcloud/donut-push:
npm i @tencentcloud/donut-push
2. 在微信开发者工具中构建 npm(微信开发者工具 -> 工具 -> 构建 npm)

使用方法

将 SDKAppID 和 appKey 替换为您在 IM 控制台 - 推送服务 Push - 接入设置页面 获取的应用的信息。如图所示:

import Push from "@tencentcloud/donut-push"
const sdkAppID = 0; // 您的 SDKAppID
const appKey = ''; // 客户端密钥
const registrationID = ""; //用户的 registrationID
const listener = (param) => {
console.log('onEvent', JSON.stringify(param));
}
App({ onLaunch: function () {
// 请确保在调用 registerPush 方法之前设置好registrationID。
// 如果您卸载并重新安装应用,registrationID 会发生改变。
Push.setRegistrationID(registrationID)
.then((res) => {
console.info("setRegistrationID", JSON.stringify(res));
return Push.registerPush(sdkAppID, appKey);
}).then((res) => {
console.info("registerPush", JSON.stringify(res));
return Push.getRegistrationID();
}).then((res) => {
console.info("getRegistrationID", JSON.stringify(res));
})
.catch((res) => {
console.error("registerPush failed", JSON.stringify(res));
});
// 监听在线推送
Push.addPushListener(Push.EventName.NOTIFICATION_CLICKED, listener);
}
})

体验您的第一次推送

在测试推送前,请务必打开通知和状态栏。进入 推送服务 Push > 接入测试 发送您的第一条推送。



推送结果回调

开启推送服务后,推送结果可以通过配置基础回调的方式,将结果转发给 App 后台,详细可参见:

设备通知栏设置

推送的直观表现就是通知栏提示,所以同其他通知一样受设备通知相关设置的影响,以华为为例:
“手机设置-通知-锁屏通知-隐藏或者不显示通知”,会影响锁屏状态下推送通知显示。
“手机设置-通知-更多通知设置-状态栏显示通知图标”,会影响状态栏下推送通知的图标显示。
“手机设置-通知-应用的通知管理-允许通知”,打开关闭会直接影响推送通知显示。
“手机设置-通知-应用的通知管理-通知铃声” 和 “手机设置-通知-应用的通知管理-静默通知”,会影响推送通知铃音的效果。


厂商推送限制

1. 国内厂商都有消息分类机制,不同类型也会有不同的推送策略。如果想要推送及时可靠,需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之,推送消息会受厂商推送消息分类影响,与预期会有差异。
2. 另外,一些厂商对于应用每天的推送数量也是有限制的,可以在厂商控制台查看应用每日限制的推送数量。 如果推送消息出现推送不及时或者偶尔收不到情况,需要考虑下这里:
华为
vivo
OPPO
小米
魅族
FCM
将推送消息分为服务与通讯类和资讯营销类,推送效果和策略不同。另外,消息分类还和自分类权益有关:
无自分类权益,推送消息厂商还会进行二次智能分类 。
有申请自分类权益,消息分类会按照自定义的分类进行推送。 具体请参见 厂商描述
将推送消息分为系统消息类和运营消息类,推送效果和策略不同。系统消息类型还会进行厂商的智能分类二次修正,若智能分类识别出不是系统消息,会自动修正为运营消息,如果误判可邮件申请反馈。另外,消息推送也受日推总数量限制,日推送量由应用在厂商订阅数统计决定。 具体请参见 厂商描述1厂商描述2
将推送消息分为私信消息类和公信消息类,推送效果和策略不同。其中私信消息是针对用户有一定关注度,且希望能及时接收的信息,私信通道权益需要邮件申请。公信通道推送数量有限制。 具体请参见 厂商描述1厂商描述2
将推送消息分为重要消息类和普通消息类,推送效果和策略不同。其中重要消息类型仅允许即时通讯消息、个人关注动态提醒、个人事项提醒、个人订单状态变化、个人财务提醒、个人状态变化、个人资源变化、个人设备提醒这8类消息推送,可以在厂商控制台申请开通。普通消息类型推送数量有限制。 具体请参见 厂商描述1厂商描述2
推送消息数量有限制。 具体请参见 厂商描述
推送上行消息频率有限制。 具体请参见厂商描述

常见问题

1. 在开发者工具上清了缓存但是构建时还是用的原来的基座 App
需要修改 project.miniapp.json 文件才能重新构建远程基座 App,改一下应用的 version code 再进行构建即可。
2. 价格及购买相关问题,请参见推送服务计费说明
3. iOS 在控制台上测试工具显示“上传 token 无效,请检查”
需要您检查下上传的 p12证书是否为推送证书、且 Bundle ID 应该是与主 App 一致。

技术咨询

点此进入腾讯云 IM 社群,享有专业工程师的支持,解决您的难题。