Android 端配置
插件配置
1. 在可视化界面添加插件,填写插件 ID 和版本号,勾选启用此插件
推送插件 ID :wx369499c8a9c4c19e
插件版本号:8.2.1
2. 设置 Donut 多端 SDK for Android 版本
3. 配置 ManifestPlaceHolders
厂商配置
1. 配置 manifestPlaceholders
注意:
推送插件集成了 vivo、HONOR 推送,需要配置 manifestPlaceholders 才能编译通过。
若不使用 vivo 和 HONOR 推送,manifestPlaceholders 的 value 设置为 “***” 即可,不能省略此处配置,否则会导致构建失败。
选中 project.miniapp.json 文件,点击右上角按钮转为 json 格式的配置文件。然后在 mini-android 节点下新增配置,填写对应的 manifestPlaceholders:
{"manifestPlaceholders": { "VIVO_APPKEY": "***", "VIVO_APPID": "***", "HONOR_APPID": "***"}}
HONOR_APPID 获取方式为:
VIVO_APPKEY 和 VIVO_APPID 获取方式分别为:
2. 配置 Gradle 插件
说明:
可根据实际情况增加/删除 push.config.json 文件中 Gradle 插件配置。例如不需要 FCM,可以删除
project -> dependencies -> com.google.gms:google-services:4.3.15 和 app -> plugins -> com.google.gms.google-services
如果 HUAWEI 、HONOR 和 FCM 厂商推送都不需要,则无需配置 Gradle 插件。
集成 HUAWEI、HONOR、FCM 推送时要依赖各自的 Gradle 插件。
在工程目录新增 Gradle 插件配置文件 push.config.json,跟 project.miniapp.json 文件同文件夹。
push.config.json 文件内容如下:
{ "project": { "dependencies": [ "com.huawei.agconnect:agcp:1.6.0.300", "com.google.gms:google-services:4.3.15", "com.hihonor.mcs:asplugin:2.0.1.300" ] }, "app": { "plugins": [ "com.huawei.agconnect", "com.hihonor.mcs.asplugin", "com.google.gms.google-services" ] } }
在插件配置文件中填入 push.config.json:
3. 配置原生应用资源文件
推送需要的原生应用资源分为两类:
1. 推送插件运行时需要从配置文件读取 appid、appkey 、证书 ID 等信息,需要把相应的 timpush-configs.json 文件放到 assets 文件夹打包到 apk 中;
2. HUAWEI、HONOR、FCM 的 Gradle 插件在构建时,需要读取各自的配置文件,就要把相应的配置文件放在 app 目录下 。
各厂商的配置文件需要分别去厂商的推送控制台下载。
然后在工程中配置资源文件:
4. 配置证书指纹(华为、荣耀)
5. 配置离线推送消息分类
iOS 端配置
插件配置
1. 在可视化界面添加插件,填写插件 ID 和版本号,勾选启用此插件,同时需要勾选启动时加载插件
推送插件 ID :wx369499c8a9c4c19e
插件版本号:8.2.1
2. 设置 Donut 多端 SDK for iOS 版本
厂商配置
1. 配置证书和描述文件
开发证书.p12
主 App 描述文件.mobileprovision
Service Extension 的描述文件.mobileprovision(可选)
注意:
Notification Service Extension (NSE) 的 Bundle ID 通常是主应用程序的 Bundle ID 后面加上扩展的标识符,生成描述文件的步骤和主 App 一致。
例如您的主 App 描述文件( BundleID为:com.yourcompany.yourapp)
那么您的 NSE 描述文件 ( BundleID为:com.yourcompany.yourapp.extension)
2. 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
4. wx369499c8a9c4c19e.json 文件的配置:
请参考关于
wx369499c8a9c4c19e.json
的配置。完成配置后,将该 JSON 文件添加到项目目录,并在 project.miniapp.json 中将其添加到插件列表中。
说明:
wx369499c8a9c4c19e.json
请在目录中创建该 json,并复制下面代码块中的内容。{ "TIMPushAppGroupID": "group.com.tencent.xxxxxxxx.xa", "businessID":"" }
5. 在 project.miniapp.json 文件中对 pushservice 进行配置 (可选)
说明:
NSE相关配置如下,其中
profilePath 表示 NSE 的描述文件。
distributeProfilePath 表示 NSE 分发时需要的描述文件。
请您按照情况填写。
"mini-plugin": { "ios": [ { "open": true, "pluginId": "wx369499c8a9c4c19e", "pluginVersion": "8.1.906", "isFromLocal": false, "loadWhenStart": true, "appexProfiles": { "NSE": { "enable": true, "bundleID": "com.tencent.xxxxxxx.pushservice", "profilePath": "impushservice.mobileprovision", "distributeProfilePath": "impushservice.mobileprovision" } }, "resourcePath": "wx369499c8a9c4c19e.json" } ] }
6. 运行前准备
完成所有配置后,当您点击 Donut 运行程序运行于真机时,会出现提示框引导您使用开发证书(.p12 文件)和主应用程序的描述文件。
注意:
当您希望利用 iOS 10 Service Extension 特性来设置 APNs 离线推送的通知图片或统计消息的到达率时,您需要在相应的 project.miniapp.json 文件中主动配置 appexProfile。同时,请确保在证书控制台中启用了 mutable-content 选项,以便充分利用 iOS 10 Service Extension 的功能。
推送插件使用
1. 加载插件
使用推送插件提供的功能前,先调用 wx.miniapp.loadNativePlugin 方法加载插件:
App({ onLaunch: function () { wx.miniapp.loadNativePlugin({ pluginId: "wx369499c8a9c4c19e", success: (plugin) => { console.log('load plugin success ', plugin) }, fail: (e) => { console.log('load plugin fail', e) } }) } })
2. 注册事件监听
注意:
1. 目前只支持点击通知事件;
2. FCM 推送不支持点击事件通知。
加载插件成功之后,先注册插件事件监听;后调用插件的 init 方法。用户点击通知栏的通知后,会发送事件,应用收到后可根据事件内容进行页面跳转。
const listener = (param) => { console.log('onMiniPluginEvent', JSON.stringify(param)) } App({ onLaunch: function () { wx.miniapp.loadNativePlugin({ pluginId: "wx369499c8a9c4c19e", success: (plugin) => { console.log('load plugin success ', plugin) plugin.onMiniPluginEvent(listener) plugin.init() }, fail: (e) => { console.log('load plugin fail', e) } }) } })
收到的点击事件数据例如:
{"data":"推送数据"}
3. 设置 registrationID (可选,默认会分配)
注意:
请确保在调用 registerPush 方法之前设置好registrationID。
说明:
如果您卸载并重新安装应用,registrationID 会发生改变。
registrationID 是推送标识 ID,用来唯一标识要进行推送的设备。如果您不主动设置它,在调用 registerPush 方法时系统会为您分配一个默认的 registrationID。如果您希望将 registrationID 与您应用中的特定账号对应起来,您可以主动设置一个 registrationID。
例如,您可以将 registrationID 设置为"99618",通过 restApi 即可向 registrationID 为 “99618” 的设备发送推送。
plugin.setRegistrationID({ registrationID: "99618"}, (ret)=>{ console.log("setRegistrationID" + ret.errCode + " " + ret.errMsg) })
回调数据格式:
成功:
{"errCode":0,"errMsg":"success"}
失败:
{"errCode":-1,"errMsg":"errorMsg"}
4. 注册 Push
插件加载成功之后,注册推送,注册成功后可接收推送,回调中带有此次注册的推送 token。
plugin.registerPush({ sdkAppID: xxx , appKey: "xxx" }, (ret)=>{ console.log("registerPush " + ret.errCode + " " + ret.errMsg) console.log("registerPush token = " + ret.data.token) })
回调数据格式:
成功:
{"errCode":0,"errMsg":"success","data":{"token":"OPPO_CN_8ed8e53d92454b29b7ef076d9d4e9834"}}
失败:
{"errCode":-1,"errMsg":"errorMsg"}
5. 获取 registrationID
在注册 Push 成功之后,可以获取到 registrationID。
plugin.getRegistrationID({}, (ret)=>{ console.log("getRegistrationID " + ret.errCode + " " + ret.errMsg + " " + ret.data.registrationID) })
回调数据格式:
成功:
{"errCode":0,"errMsg":"success","data":{"registrationID":"99618"}}
失败:
{"errCode":-1,"errMsg":"errorMsg"}
6. 反注册 Push
反注册关闭推送。
plugin.unRegisterPush({}, (ret)=>{ console.log("unRegister " + ret.errCode + " " + ret.errMsg) })
回调数据格式:
成功:
{"errCode":0,"errMsg":"success"}
失败:
{"errCode":-1,"errMsg":"errorMsg"}
推送测试
完成上述配置后,要向设备下发推送进行测试。有两个步骤:
1. 获取 registrationID
a. 加载插件后,直接调用 registerPush 方法注册推送,注册成功后,可通过 getRegistrationID 方法获取到 registrationID。
b. 也可以先通过 setRegistrationID 方法设置自定义的 registrationID,再进行注册。
2. 用 restApi 发送推送消息
在单发推送时,restApi 请求的 To_Account 字段填入上一步获取到的 registrationID。
例如,registrationID 是 "99618",则 REST API 请求 URL 为:
https://console.tim.qq.com/v4/tpush/batch?usersig=<admin 账号的 userSig>&identifier=admin&sdkappid=<您的 sdkAppID>&random=99999999&contenttype=json
说明:
使用 REST API 时 URL 中尖括号内及其内的内容替换为实际值。
请求包为:
{ "From_Account": "admin", "To_Account": ["99618"], // 数组长度范围在[1,500]之间 "MsgRandom": 3674128, "OfflinePushInfo": { "PushFlag": 0, // 0 表示进行推送,1 表示不进行推送 "Title": "离线推送标题", "Desc": "离线推送内容", "Ext":"点击事件通知数据" // 可选, value 请填写 JSON 格式的字符串 } }
常见问题
1. 插件配置之后,调用 wx.miniapp.loadNativePlugin 方法,报错:load plugin fail
首先请检查配置的插件 ID 前后有没有空格,再检查版本号是否正确。
2. 在开发者工具上清了缓存但是构建时还是用的原来的基座 App
需要修改 project.miniapp.json 文件才能重新构建远程基座 App,改一下应用的 version code 再进行构建即可。
3. 价格及购买相关问题,详细参见推送服务计费说明。
4. iOS 在控制台上测试工具显示 上传 token 无效,请检查
需要您检查下上传的 p12证书是否为推送证书、且Bundle ID应该是与主 App 一致。