体验反馈:
您在文档接入过程中是否遇到困难?接入过程是否显得过于复杂?无论是建议、疑惑还是吐槽,都欢迎在这里向我们反馈。希望各位开发者能在闲暇时花费1分钟填写 TUIKit for uni-app 体验反馈。我们将根据您的反馈优化 TUIKit,以提升您的使用体验。
前置条件
1. 集成 Chat TUIKit,可参见 含 UI 集成方案(荐) -> 集成基础功能 ->uni-app(Vue2/Vue3)
说明:
1. 已集成 Chat TUIKit 可忽略此步骤。
2. 无 UI 集成 Chat 可忽略此步骤。
2. 升级 @tencentcloud/chat 到最新版本。
说明:
npm install @tencentcloud/chat@latest
在 HBuilder 日志中查看 TencentCloudChat.VERSION 版本号,来确认 @tencentcloud/chat ≥ 3.2.5 如图所示:
3. 开通推送插件
4. 厂商配置
说明:
集成 TencentCloud-TIMPush
步骤1:manifest.json App 模块配置
在项目 manifest.json > App 模块配置中配置消息推送模块,如图所示:
步骤2:项目引入 TencentCloud-TIMPush,填写相关参数。
1. 将 TencentCloud-TIMPush 引入项目中。
说明:
1. TencentCloud-TIMPush 支持云打包、本地打包和离线打包。
2. 强烈推荐云打包方案,其接入过程简洁明了,且使用起来极为便利迅速。
3. 当您需要锁定特定版本的 TencentCloud-TIMPush 时,本地打包将是您的理想之选。
4. 若您的团队已拥有本地原生打包服务或正进行原生开发工作,离线打包将更加符合您的需求。
注意:
1. 插件市场开通云打包服务项目的 appId 需要和项目 manifest.json 中的 appid 一致。
2. 开通云打包服务的 TencentCloud-TIMPush 仅用于一个项目。仅与项目有关。
前置条件:
1. 应用中已集成 TencentCloud-TIMPush。
2. 应用已完成 uni-app 离线打包。
3. 下载 TencentCloud-TIMPush 插件到本地。
4. Android Studio / Xcode。
2. 在项目的 manifest.json > App 原生插件配置 中勾选 TencentCloud-TIMPush,并设置相关参数。
注意:
1. 云打包选择云端插件,本地打包选择本地插件。
2. 注意在 HBuilderX 中参数可能会出现乱序现象,请仔细认真填写。
3. 各个参数为必填项,否则会编译错误,默认为 0。
说明:
com.hihonor.push.app_id 对应 hihonor 的 appID。
不启用 hihonor 推送时,com.hihonor.push.app_id 默认设置为 0 即可。
控制台配置 | manifest.json 荣耀配置 |
| |
说明:
com.vivo.push.api_id 对应 vivo 的 appID。
com.vivo.push.api_key 对应 vivo 的 appKey。
不启用 vivo 推送时,com.vivo.push.api_id 和 com.vivo.push.api_key 默认设置为 0 即可。
控制台配置 | manifest.json vivo 配置 |
| |
注意:
不配置 TIMPushAppGroupID 不会影响正常推送功能。
不启动 iOS 的触达上报时,TIMPushAppGroupID 默认设置为 0 即可;
iOS appGroupID 生成指引 | manifest.json iOS 配置 |
|
3. 配置 agconnect-services.json 文件(仅华为)到 nativeResources/android/assets/ 目录下。如图所示:
说明:
1. 华为推送需要配置 agconnect-services.json 文件,其他厂商可忽略。
2. agconnect-services.json 配置和获取可参见 厂商配置 > uni-app > 华为 > 步骤4:获取应用信息。
步骤3: manifest.json Android 权限配置
在项目的 manifest.json > 源码视图 > app-plus > distribute > android > permissions 中追加以下权限项,如图所示:
"<uses-permission android:name=\\"android.permission.INTERNET\\" />","<uses-permission android:name=\\"android.permission.ACCESS_NETWORK_STATE\\" />","<uses-permission android:name=\\"android.permission.ACCESS_WIFI_STATE\\" />","<uses-permission android:name=\\"android.permission.WRITE_EXTERNAL_STORAGE\\" />"
步骤4. 注册 TencentCloud-TIMPush
注意:
@tencentcloud/chat ≥ 3.2.5 支持 TencentCloud-TIMPush。
androidConfig 是 Android 推送配置,如不需要打包 Android App,可传空。
iOSConfig 是 iOS 推送配置,如不需要打包 iOS App, 可传空。
在 App.vue 中引入 TencentCloud-TIMPush,并挂载到 uni 上。
在 App.vue 中引入 timpush-configs.json,并挂载到 uni 上。
// #ifdef APP-PLUSimport TIMPushConfigs from "./timpush-configs.json";const TIMPush = uni.requireNativePlugin("TencentCloud-TIMPush");console.warn(`TencentCloud-TIMPush: uni.requireNativePlugin ${!!TIMPush ? 'success' : 'fail'}`);uni.$TIMPush = TIMPush;uni.$TIMPushConfigs = TIMPushConfigs || {};// #endif
确认 uni.requireNativePlugin 引入 TencentCloud-TIMPush 成功,如图所示:
在 uikit 登录时,将 TencentCloud-TIMPush 注册进 uikit.
import { TUILogin } from "@tencentcloud/tui-core";TUILogin.login({SDKAppID: 0, // 接入时需要将0替换为您的即时通信应用的 SDKAppIDuserID: '',// UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。// 该方法仅适合本地跑通 Demo 和功能调试,详情请参见 https://cloud.tencent.com/document/product/269/32688userSig: '',// 如果您需要发送图片、语音、视频、文件等富媒体消息,请设置为 trueuseUploadPlugin: true,framework: `vue${vueVersion}` // 当前开发使用框架 vue2 / vue3TIMPush: uni.$TIMPush, // APP 注册推送插件pushConfig: {androidConfig: uni.$TIMPushConfigs, // Android 推送配置,如不需要可传空。iOSConfig: {"iOSBusinessID": "" // iOS 推送配置,如不需要可传空。}}})
在 chat 登录前,需要将 TencentCloud-TIMPush 注册进 chat 中.
import TencentCloudChat from '@tencentcloud/chat';const chat = TencentCloudChat.create({SDKAppID: 0}) // 接入时需要将0替换为您的即时通信应用的 SDKAppIDchat.registerPlugin({'tim-push': uni.$TIMPush,pushConfig: {androidConfig: uni.$TIMPushConfigs, // Android 推送配置,如不需要可传空。iOSConfig: {"iOSBusinessID": "xxx" // iOS 推送配置,如不需要可传空。}}})chat.login({userID: '', // 用户 ID。userSig: '' // 用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。具体生成方法请参见 https://cloud.tencent.com/document/product/269/32688})
步骤5. 生成自定义基座
单击 HBuilderX 的 运行 > 运行到手机或模拟器 > 制作自定义调试基座制作自定义基座。
注意:
配置原生插件,必须打包自定义基座进行测试。
制作基座时,Android 包名为插件开通云打包时绑定的应用包名。
证书使用云端证书。
步骤6. 运行并登录项目,确认 TencentCloud-TIMPush 集成成功。
运行时,选择自定义基座运行,在 HBuilder 的日志中,确认有
TIMPushModule._setToken ok
打印,表示 TencentCloud-TIMPush 集成成功,如图所示:
步骤7. 体验您的第一次离线推送。
注意:
接收端的应用必须置于后台,或者结束进程的状态。
直播群不支持离线消息推送。
更多高级特性(强烈推荐)
1. 设置推送内容
在 uikit 中使用 TUIChatService 发送消息时,设置 offlinePushInfo 相关参数,如发送普通文本消息,代码如下:
// 发送普通文本消息let promise = TUIChatService.sendTextMessage({payload: { text: 'Hello world!' }},{// 如果接收方不在线,则消息将存入漫游,且进行离线推送(在接收方 App 退后台或者进程被 kill 的情况下)。接入侧可自定义离线推送的标题及内容offlinePushInfo: {title: '', // 离线推送标题。description: '', // 离线推送内容。extension: '', // 离线推送透传内容}});promise.catch((error) => {// 调用异常时业务侧可以通过 promise.catch 捕获异常进行错误处理});
在 chat 发送消息时,设置 offlinePushInfo 相关字段,代码如下:
// 消息发送选项chat.sendMessage(message, {// 如果接收方不在线,则消息将存入漫游,且进行离线推送(在接收方 App 退后台或者进程被 kill 的情况下)。接入侧可自定义离线推送的标题及内容offlinePushInfo: {title: '', // 离线推送标题。description: '', // 离线推送内容。extension: '', // 离线推送透传内容}});
参考文档:
2. 获取点击透传的内容
在
App.vue
文件中获取透传内容,配置指定跳转页面。onLaunch: function () {// #ifdef APP-PLUS// 在 App.vue, 生命钩子 onLaunch 中监听if (uni.$TIMPush) {uni.$TIMPush.setOfflinePushListener((data) => {// 透传 entity 中的内容,不包含推送的 Messageconsole.log('setOfflinePushListener', data);// 跳转到应用内指定界面uni.navigateTo({url: "/pages/xxx/xxx",});});}// #endif}
注意:
可在此获取推送时配置的透传内容。
可在此配置应用跳转界面。
各端互通时,要确保
extension
保持一致, extension
中需要包含 entity
字段。3. 推送结果回调
开启推送插件后,推送结果可以通过配置基础回调的方式,将结果转发给 App 后台。详情可参见:
普通推送结果回调
全员推送结果回调
4. 支持 TUICallKit 离线唤醒
应用在后台时或离线时 | 锁屏时 |
| |
异常排查
数据统计
设备通知栏设置
推送的直观表现就是通知栏提示,所以同其他通知一样受设备通知相关设置的影响,以华为为例:
“手机设置-通知-锁屏通知-隐藏或者不显示通知”,会影响锁屏状态下离线推送通知显示。
“手机设置-通知-更多通知设置-状态栏显示通知图标”,会影响状态栏下离线推送通知的图标显示。
“手机设置-通知-应用的通知管理-允许通知”,打开关闭会直接影响离线推送通知显示。
“手机设置-通知-应用的通知管理-通知铃声” 和 “手机设置-通知-应用的通知管理-静默通知”,会影响离线推送通知铃音的效果。
厂商推送限制
1. 国内厂商都有消息分类机制,不同类型也会有不同的推送策略。如果想要推送及时可靠,需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之,离线推送消息会受厂商推送消息分类影响,与预期会有差异。
2. 另外,一些厂商对于应用每天的推送数量也是有限制的,可以在厂商控制台查看应用每日限制的推送数量。 如果离线推送消息出现推送不及时或者偶尔收不到情况,需要考虑下情况:
华为 | vivo | OPPO | 小米 | 魅族 | FCM |
将推送消息分为服务与通讯类和资讯营销类,推送效果和策略不同。另外,消息分类还和自分类权益有关: 无自分类权益,推送消息厂商还会进行二次智能分类 。 有申请自分类权益,消息分类会按照自定义的分类进行推送。 具体请参见 厂商描述。 |
常见问题
1. TencentCloud-TIMPush 和 uniPush2 冲突了,不能共用该如何处理?
2. 推送有报错 "TIMPushModule._getDeviceToken failed. error: { "code": -1, "msg": "huawei ApiException: com.huawei.hms.common.ApiException: 907135000: arguments invalid"}"。
原因:华为 agconnect-services.json 文件未引入。
解决方案:检查华为 agconnect-services.json 文件是否引入。
注意:
华为推送需要将官网下载的 agconnect-services.json 文件放到
nativeResources/android/assets
路径下。详细可参见 uni-app 厂商配置 - Android - 华为。3. 推送有报错 “TIMPushModule._getDeviceToken failed. error:{"code":-1, "msg": "callback is not String"}”。
原因:华为版本过低,EMUI 版本需要大于 10。
解决方案:升级或换EMUI 版本 > 10 的华为进行推送。
4. 推送有报错 "TIMPushModule._getDeviceToken failed. error:{"code":22022,"msg":"xiaomi error code: 22022"}"。
原因:应用程序 package name 不合法。
5. 推送只能收到1~2次,后续收不到推送。
原因:厂商推送限制。
6. OPPO 手机收不到推送?
原因: OPPO 安装应用通知栏显示默认关闭。
解决方案:开启通知栏显示状态。
7. 按照流程接入完成,还是收不到推送?
原因:
设备状态异常、 IM 控制台配置未配置、初始化未注册等。
推送依赖厂商能力,一些简单的字符可能会被厂商过滤不能透传推送。
如果推送消息出现推送不及时或者偶尔收不到情况,需要看下厂商的推送限制。
解决方案:
可通过排查工具来进行排查。
检查发送内容,避免使用简单字符。
检查厂商推送限制,详情可见厂商推送限制。
8. iOS 普通消息为什么收不到离线推送?
原因:App 的运行环境和证书的环境是否不一致。
解决方案:
检查 App 的运行环境和证书的环境是否一致,如果不一致,收不到离线推送。
检查下 App 和证书的环境是否为生产环境。如果是开发环境,向苹果申请 deviceToken 可能会失败,生产环境暂时没有发现这个问题,请切换到生产环境测试。
9. iOS 开发环境下,注册偶现不返回 deviceToken 或提示 APNs 请求 token 失败?
原因:此问题现象是由于 APNs 服务不稳定导致的。
解决方案:
给手机插入 SIM 卡后使用4G网络测试。
卸载重装、重启 App、关机重启后测试。
在生产环境中打包测试。
更换其它 iOS 系统的手机测试。
10. iOS 没有 token的原因 ?
原因:
模拟器不产生 token。
真机,需要在手机上开启推送的权限。
真机,需要添加 push notification 的 enetitemenet。
解决方案:使用真机开启推送权限,并添加 push notification 的 enetitemenet。