Docs Overview/
uniapp/

uniapp

前置条件

1. 集成 Chat TUIKit，可参见 含 UI 集成方案（荐） -> 集成基础功能 ->uni-app（Vue2/Vue3）

说明：
1. 已集成 Chat TUIKit 可忽略此步骤。
2. 无 UI 集成 Chat 可忽略此步骤。

2. 升级 @tencentcloud/chat 到最新版本。

说明：
@tencentcloud/chat 向下兼容，可放心升级。如果您当前用的是 tim-js-sdk 或 tim-wx-sdk，请参考我们的升级指引。
npm install @tencentcloud/chat@latest
在 HBuilder 日志中查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat ≥ 3.2.5 如图所示：




3. 开通推送插件

进入 IM 控制台 > 插件市场，单击立即购买或免费试用 。（每个应用可免费试用一次，有效期7天。）



注意：
推送插件试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等服务）。为避免影响您业务正常使用，请提前购买/续费。

4. 厂商配置

说明：
uniapp 厂商配置包含 Android 厂商配置 和 iOS 厂商配置， 可参见 厂商配置 - uniapp。

集成 TencentCloud-TIMPush

步骤1：manifest.json App 模块配置

在项目 【manifest.json】 > 【App 模块配置】 中配置消息推送模块，如图所示：





步骤2：开通 TencentCloud-TIMPush 云打包服务，填写相关参数。

1. 前往插件市场，开通 TencentCloud-TIMPush 云打包服务。如图所示：
注意：
1. 插件市场开通云打包服务项目的 appId 需要和项目 manifest.json 中的 appid 一致。
2. 开通云打包服务的 TencentCloud-TIMPush 仅用于一个项目。仅与项目有关。



2. 在项目的 【manifest.json】 >【 App 原生插件配置】 > 【云端插件】中勾选 TencentCloud-TIMPush，并设置相关参数。
注意：
1. 注意在 HBuilderX 中参数可能会出现乱序现象，请仔细认真填写。
2. 各个参数为必填项，否则会编译错误，默认为 0。
com.hihonor.push.app_id
com.vivo.push.app_id && com.vivo.push.api_key
TIMPushAppGroupID
说明：
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 的 appGroupID，它是 iOS 的触达上报的配置项，可参考 configuring-app-groups 生成 appGroupID。
注意：
不配置 TIMPushAppGroupID 不会影响正常推送功能。
不启动 iOS 的触达上报时，TIMPushAppGroupID 默认设置为 0 即可；
iOS appGroupID 生成指引
manifest.json iOS 配置
可参考 configuring-app-groups 生成 appGroupID




步骤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， 可传空。
获取 Android 配置 timpush-configs.json
获取 iOS 配置 iOSBusinessID
timpush-configs.json 可以在 IM控制台 > 推送 > 接入设置 进行下载, 并将 timpush-configs.json 放入 App.vue 同级目录中， 如图所示：






iOS iOSBusinessID 可以在 IM 控制台 > 推送 > 接入设置获取，如图所示：



App.vue
含 UI 集成
无 UI 集成
在 App.vue 中引入 TencentCloud-TIMPush，并挂载到 uni 上。
在 App.vue 中引入 timpush-configs.json，并挂载到 uni 上。
// #ifdef APP-PLUS
import 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替换为您的即时通信应用的 SDKAppID
    userID: '',
    // UserSig 是用户登录即时通信 IM 的密码，其本质是对 UserID 等信息加密后得到的密文。
    // 该方法仅适合本地跑通 Demo 和功能调试，详情请参见 https://cloud.tencent.com/document/product/269/32688     
    userSig: '', 
    // 如果您需要发送图片、语音、视频、文件等富媒体消息，请设置为 true
    useUploadPlugin: true,
    framework: `vue${vueVersion}` // 当前开发使用框架 vue2 / vue3
    TIMPush: 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替换为您的即时通信应用的 SDKAppID
chat.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. 接收您的第一条推送。

进入 IM 控制台推送 > 推送测试发送您的第一条推送。如图所示：
注意：
1. 接收端的应用必须置于后台，或者结束进程的状态。
2. 直播群不支持离线消息推送。


更多高级特性（强烈推荐）

1. 设置推送内容

含 UI 集成
无 UI 集成
在 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: '', // 离线推送透传内容
  }
});
参考文档：
Chat SDK - sendMessage 文档

2. 获取点击透传的内容

在 App.vue 文件中获取透传内容，配置指定跳转页面。
onLaunch: function () {
   // #ifdef APP-PLUS
   // 在 App.vue, 生命钩子 onLaunch 中监听
   if (uni.$TIMPush) {
    uni.$TIMPush.setOfflinePushListener((data) => {
        // 透传 entity 中的内容，不包含推送的 Message
        console.log('setOfflinePushListener', data);
        // 跳转到应用内指定界面
        uni.navigateTo({
            url: "/pages/xxx/xxx",
        });
    });
   }
   // #endif
}
注意：
可在此获取推送时配置的透传内容。
可在此配置应用跳转界面。
各端互通时，要确保 extension 保持一致， extension 中需要包含 entity 字段。

异常排查

如果用户在 App 离线时，未收到离线推送消息，可以通过排查工具来全链路排查推送详情。




数据统计

查询用户所有推送数据，整理和分析用户每日推送各类型指标数据，生成近日发送 > 触达 > 点击漏斗转化图表，支持按照厂商通道分类查看。




设备通知栏设置

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




厂商推送限制

1. 国内厂商都有消息分类机制，不同类型也会有不同的推送策略。如果想要推送及时可靠，需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之，离线推送消息会受厂商推送消息分类影响，与预期会有差异。
2. 另外，一些厂商对于应用每天的推送数量也是有限制的，可以在厂商控制台查看应用每日限制的推送数量。 如果离线推送消息出现推送不及时或者偶尔收不到情况，需要考虑下这里：

华为
vivo
OPPO
小米
魅族
FCM
将推送消息分为服务与通讯类和资讯营销类，推送效果和策略不同。另外，消息分类还和自分类权益有关： 无自分类权益，推送消息厂商还会进行二次智能分类 。 有申请自分类权益，消息分类会按照自定义的分类进行推送。 具体请参见 厂商描述 。
将推送消息分为系统消息类和运营消息类，推送效果和策略不同。系统消息类型还会进行厂商的智能分类二次修正，若智能分类识别出不是系统消息，会自动修正为运营消息，如果误判可邮件申请反馈。另外，消息推送也受日推总数量限制，日推送量由应用在厂商订阅数统计决定。 具体请参见 厂商描述1 或 厂商描述2 。
将推送消息分为私信消息类和公信消息类，推送效果和策略不同。其中私信消息是针对用户有一定关注度，且希望能及时接收的信息，私信通道权益需要邮件申请。公信通道推送数量有限制。 具体请参见 厂商描述1 或 厂商描述2 。
将推送消息分为重要消息类和普通消息类，推送效果和策略不同。其中重要消息类型仅允许即时通讯消息、个人关注动态提醒、个人事项提醒、个人订单状态变化、个人财务提醒、个人状态变化、个人资源变化、个人设备提醒这8类消息推送，可以在厂商控制台申请开通。普通消息类型推送数量有限制。 具体请参见 厂商描述1 或 厂商描述2 。
推送消息数量有限制。 具体请参见 厂商描述 。
推送上行消息频率有限制。 具体请参见 厂商描述 。
华为：将推送消息分为服务与通讯类和资讯营销类，推送效果和策略不同。另外，消息分类还和自分类权益有关：
无自分类权益，推送消息厂商还会进行二次智能分类 。
有申请自分类权益，消息分类会按照自定义的分类进行推送。 具体请参见 厂商描述。
vivo：将推送消息分为系统消息类和运营消息类，推送效果和策略不同。系统消息类型还会进行厂商的智能分类二次修正，若智能分类识别出不是系统消息，会自动修正为运营消息，如果误判可邮件申请反馈。另外，消息推送也受日推总数量限制，日推送量由应用在厂商订阅数统计决定。 具体请参见 厂商描述1 或 厂商描述2。
OPPO：将推送消息分为私信消息类和公信消息类，推送效果和策略不同。其中私信消息是针对用户有一定关注度，且希望能及时接收的信息，私信通道权益需要邮件申请。公信通道推送数量有限制。 具体请参见 厂商描述1 或 厂商描述2。
小米：将推送消息分为重要消息类和普通消息类，推送效果和策略不同。其中重要消息类型仅允许即时通讯消息、个人关注动态提醒、个人事项提醒、个人订单状态变化、个人财务提醒、个人状态变化、个人资源变化、个人设备提醒这8类消息推送，可以在厂商控制台申请开通。普通消息类型推送数量有限制。 具体请参见 厂商描述1 或 厂商描述2。
魅族：推送消息数量有限制。 具体请参见 厂商描述。
FCM：推送上行消息频率有限制。 具体请参见 厂商描述。

常见问题

1. TencentCloud-TIMPush 和 uniPush2 冲突了，不能共用该如何处理？

原因：TencentCloud-TIMPush 不支持与其他离线推送通道共用。
解决方案：推荐仅使用 TencentCloud-TIMPush 即可。

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 路径下。详细可参见 uniapp 厂商配置 - 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 不合法。
解决方案：前往小米推送平台检查应用的包名、appId、appKey 是否匹配 。具体可参见： 厂商通道注册失败排查指南。

5. OPPO 手机收不到推送？

原因: OPPO 安装应用通知栏显示默认关闭。
解决方案：开启通知栏显示状态。

6. 按照流程接入完成，还是收不到推送？

原因：
设备状态异常、 IM 控制台配置未配置、初始化未注册等。
推送依赖厂商能力，一些简单的字符可能会被厂商过滤不能透传推送。
如果推送消息出现推送不及时或者偶尔收不到情况，需要看下厂商的推送限制。
解决方案:
可通过排查工具来进行排查。
检查发送内容，避免使用简单字符。
检查厂商推送限制，详情可见厂商推送限制。

7. iOS 普通消息为什么收不到离线推送?

原因：App 的运行环境和证书的环境是否不一致。
解决方案：
检查 App 的运行环境和证书的环境是否一致，如果不一致，收不到离线推送。
检查下 App 和证书的环境是否为生产环境。如果是开发环境，向苹果申请 deviceToken 可能会失败，生产环境暂时没有发现这个问题，请切换到生产环境测试。

8. iOS 开发环境下，注册偶现不返回 deviceToken 或提示 APNs 请求 token 失败？

原因：此问题现象是由于 APNs 服务不稳定导致的。
解决方案：
给手机插入 SIM 卡后使用4G网络测试。
卸载重装、重启 App、关机重启后测试。
打生产环境的包测试。
更换其它 iOS 系统的手机测试。

9. iOS 没有 token的原因 ?

原因：
模拟器不产生 token。
真机，需要在手机上开启推送的权限。
真机，需要添加 push notification 的 enetitemenet。
解决方案：使用真机开启推送权限，并添加 push notification 的 enetitemenet。

10. tim-js-sdk 可以使用 TIMPush 吗？

原因: 不支持 TencentCloud-TIMPush；
解决方案：升级 @tencentcloud/chat 接入，@tencentcloud/chat 是向下兼容的，不会影响 tim-js-sdk 实现的业务。

技术咨询

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