# TPNS使用指南 ## 一、使用前须知 **特别说明** - 腾讯云移动推送 TPNS 已停止售卖，[查看公告](https://cloud.tencent.com/document/product/548/103030)；仅支持免费试用，[查看详情](https://cloud.tencent.com/document/product/548/47976)。 - 当前框架层正在对接新版本的腾讯云消息推送，详情可查看[新版消息推送](impush)，建议开发者接入新版本的消息推送服务。 - 补充：下方的操作指南只适用于 20241015 之前的旧版本的开发者工具；以及，存量已接入 TPNS 的服务不受影响，可继续使用，但依旧建议开发者尽早切换为新版本的[腾讯云消息推送](impush) ## 二、操作指南 本章节的操作指南仅包含开发者工具上的操作，腾讯云控制台相关的操作可前往[腾讯云移动推送](https://cloud.tencent.com/document/product/548)查看 ### 1、Android 消息推送 #### a) 下载配置文件 - 前往[移动推送控制台](https://console.cloud.tencent.com/tpns/product)，进入「App 推送管理 - 基础配置」，点击下载「配置文件」 ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202306282100623.png) **其他注意事项** 1、如开发者在腾讯云消息推送控制台更新了相关配置，开发者亦需要在开发者工具这边更新至最新的配置文件 #### b) 修改 SDK 版本 - 下载版本号 ≥ 1.06.2306282 的[开发者工具](/miniprogram/dev/devtools/log.md)，进入到多端模式后，点击 `project.miniapp.json` - 将 Android SDK 版本改为 1.0.4 及以上版本 ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202306282110425.png) #### c) 启用消息推送并配置 tpns-configs.json - 在 `project.miniapp.json` 的「扩展 SDK」中配置启用消息推送以及 tpns-configs.json，操作如下截图 ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E6%88%AA%E5%9B%BE_6450b0da-c66c-41e7-9460-87b66110880f.png) #### d) 前往腾讯云发起消息推送 - 详情可查看[创建推送任务](https://cloud.tencent.com/document/product/548/37243) ### 2、iOS 消息推送 #### a) 获取推送证书 - 需按照腾讯云文档指引，在移动推送服务中注册 iOS 推送证书，详情可查看[推送证书获取指引](https://cloud.tencent.com/document/product/548/36664) - 同时按照上面的文档，多创建一个新的 Bundle Id 用于「通知服务扩展」能力（即，苹果的 Notification Service Extension）； - 此外，后续需在开发者工具的 `project.miniapp.json` 中设置 serviceBundleId，且新建的时候选择的 certificate 证书使用需与 App 的一致。 - 以及，开发者需下载保存好 Bundle Id 对应的 Profile（运行就用开发版，构建发布就用正式版），需在开发者工具上使用到 **注意** - 主工程的 Bundle Id 和 Service 的 Bundle Id 必须不同，且 Service 的 Bundle Id 必须以主工程的 Bundle Id 为前缀（例如，主工程的 Bundle Id：com.tencent.tpns，Service 的 Bundle Id：com.tencent.tpns.service）。 - certificate 必须和 App 的一致 #### b) 启用消息推送并配置相关信息 - 在 `project.miniapp.json` 的「扩展 SDK」中配置启用消息推送以及配置 AccessID、AccessKey 以及 serviceBundleId ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202307182258647.png) - 配置成功后，就可以开始运行/构建 IPA，需使用「证书签名」的方式，不可使用「临时签名」的方式 - 启用消息推送能力后，签名时会提示需对额外的 Notification Service Extension 的 Profile 进行签名，而这个 Profile 就是在步骤 a) 中保存的 Profile Windows：签名的时候，在 NSE Profile 中选择对应的 profile ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202407171522353.png) Mac：使用了消息推送以后会出现以下选择框 ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202407171523849.png) ## 三、API 列表 完成上述配置后，需调用如下 JSAPI 使用消息推送功能： - [wx.miniapp.getXGPushManager](/miniprogram/dev/platform-capabilities/miniapp/api/miniapp/tpnsApi) ## 四、其他说明 - iOS 的厂商通道接入已支持；Android 的厂商通道接入也已支持，覆盖的通道包含：[华为](https://cloud.tencent.com/document/product/548/45909)、[荣耀](https://cloud.tencent.com/document/product/548/45909)、[小米](https://cloud.tencent.com/document/product/548/36654)、[魅族](https://cloud.tencent.com/document/product/548/36655)、[VIVO](https://cloud.tencent.com/document/product/548/36657)、[OPPO](https://cloud.tencent.com/document/product/548/36658)；注意，需选择 1.0.4 或以上的版本 - **注意事项**：Android 的 targetVersion 建议设置为 33。 - ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202309041641697.png) - 此外，如果使用华为的通道，可参考下方配置华为依赖包的版本 ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202403111638240.png) ## 五、如何关闭使用消息推送 SDK - 如开发者不再使用消息推送 SDK，可在 `project.miniapp.json` 的「扩展 SDK」中配置「不勾选」启用消息推送 SDK 即可 - 配置完成后，重新构建新的安装包即可 ## 六、常见问题 ### 1. XGPush_registerPush:fail - 消息推送的能力不支持在移动应用助手中调试，开发者需构建 APK 安装到手机上进行测试 ### 2. TpnsPlugin ERROR - 如果配置了 tpns-configs.json 仍出现下方报错，开发者需检查腾讯云移动推送控制台上配置的包名和在微信开发者工具构建 APK 的包名是否一致 ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202308071716647.png) ### 3.推送失败 如自测发现推送失败，可前往腾讯云控制台使用相关排查工具进行排查；若自查后仍有问题，请联系腾讯云客服。 ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E6%88%AA%E5%9B%BE_3a685d81-e072-4834-9612-b224c59f8b3b.png)