更新记录

1.1.0（2024-03-23）

Android：

1. vivo升级推送包 4.0.0.0；
2. vivo、oppo 厂商偶现崩溃问题优化；
3. 解决杀进程不回调。

iOS： 1.新增 Extension 插件，支持触达上报。

1.0.0（2024-02-28）

修复 android：TencentCloud-TIMPush 与 TencentCloud-TUICallKit 插件共同使用时，无法打包的问题。

0.1.0（2024-01-24）

• 支持 android 小米、华为、荣耀、OPPO、vivo、魅族、APNs、一加、realme、iQOO、 FCM 等厂商通道；
• 支持 ios

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

概述

TencentCloud-TIMPush 为您提供稳定、及时、多样化的推送服务。相比自集成推送，推送插件只需进行简单配置，即可一键式集成接入多个厂商的推送服务。推送插件支持普通消息推送和全员/标签推送，提供完整的推送生命周期查询、数据统计、问题排查服务。 如果您有聊天、音视频通话、信令等场景，需要离线场景也能及时触达，可以关注普通消息推送功能。 如果您有营销广告、通知、新闻资讯等需要推送给所有用户或指定群体，可以关注全员/标签推送功能。 离线推送厂商支持小米、华为、荣耀、OPPO、vivo、魅族、APNs，包含各厂商子品牌如一加、realme、iQOO 等，境外支持 Google FCM。 推送管理控制台为您提供全链路排查工具、推送记录和各类型指标统计数据，方便您查看推送触达率、点击率和转化率等各类指标。

功能介绍

3分钟快速集成

不再需要逐个厂商分别配置推送信息，只需在 IM 控制台下载引入 json 配置文件，即可一键式完成所有手机厂商的推送信息配置。 支持按需集成一个或者多个对应厂商的推送渠道包，轻松应对合规要求。 不需要自行处理推送注册、token 上报、前后台状态上报等，推送插件自闭环。 不再需要自行添加打点和处理上报逻辑，推送插件自行上报和汇总，还支持链路排查和指标统计等。 插件封装界面跳转、图标自定义等方法，直接使用即可。

普通消息推送

在普通 IM 消息收发场景，应用离线下消息也可及时抵达设备并支持定制跳转界面。

全员/标签推送

全员/标签推送功能旨在帮助您向全员或者标签用户，进行营销、广告和通知等类型的推送，保证在合适的时机用合适的方式给合适的用户发送合适的消息。

全员/标签推送支持落地和不落地两种推送方式：

落地推送

支持漫游，推送消息也会进入 IM 消息系统，会触发对应会话、消息和未读等模块更新，用户在线时候可以收到推送的消息，用户不在线时候下次登录后可自动拉取到推送的消息。

不落地推送

推送消息产生系统通知抵达设备，消息不会保存在 IM 系统。

自定义跳转界面

收到推送后，用户单击了通知栏，支持自定义跳转界面。

推送自定义样式

支持小图标、右侧图标、长文本、大图片、角标和铃音自定义样式。

设备推送状态查询

集成推送插件完成后，可以使用控制台接入测试功能自查各个厂商是否配置正常，达到可推送状态。

全链路排查工具

提供自助式排查工具，支持查看整个推送链路详情，支持分析推送失败和点击失败原因，提升转化。

统计数据

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

• 推送指标分析

  

• 推送记录

  

前置条件

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

   说明：

   • 已集成 Chat TUIKit 可忽略此步骤。
   • 无 UI 集成 Chat 可忽略此步骤。

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

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 云打包服务。如图所示：

   注意：

   • 插件市场开通云打包服务项目的 appId 需要和项目 manifest.json 中的 appid 一致。
   • 开通云打包服务的 TencentCloud-TIMPush 仅用于一个项目。仅与项目有关。

2. 在项目的 【manifest.json】 >【 App 原生插件配置】 > 【云端插件】中勾选 TencentCloud-TIMPush，并设置相关参数。

   注意：

   • 注意在 HBuilderX 中参数可能会出现乱序现象，请仔细认真填写。
   • 各个参数为必填项，否则会编译错误，默认为 0。

com.hihonor.push.app_id

说明：

• com.hihonor.push.app_id 对应 hihonor 的 appID。
• 不启用 hihonor 推送时，com.hihonor.push.app_id 默认设置为 0 即可。

控制台配置	manifest.json 荣耀配置

com.vivo.push.app_id && com.vivo.push.api_key

说明：

• 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

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

• 在 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 成功，如图所示：

  含 UI 集成

  在 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 推送配置，如不需要可传空。
      }    
  }
  })

  无 UI 集成

  在 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. 设置推送内容

含 UI 集成

在 uikit 中使用 TUIChatService 发送消息时，设置 offlinePushInfo 相关参数，如发送普通文本消息，代码如下：

// 发送普通文本消息
let promise = TUIChatService.sendTextMessage(
{ 
   payload: {   text: 'Hello world!' }
},
{
  // 如果接收方不在线，则消息将存入漫游，且进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容
   offlinePushInfo: {
     title: '', // 离线推送标题。
     description: '', // 离线推送内容。
     extension: '', // 离线推送透传内容
   }
}
);
promise.catch((error) => { 
    // 调用异常时业务侧可以通过 promise.catch 捕获异常进行错误处理
});

参考文档：uikit - TUIChatService 发送消息相关文档

无 UI 集成

在 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 字段。

3. 推送结果回调

开启推送插件后，推送结果可以通过配置基础回调的方式，将结果转发给 App 后台。详情可参见：

• 普通推送结果回调
• 全员推送结果回调

  异常排查

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

数据统计

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

设备通知栏设置

推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：

• “手机设置-通知-锁屏通知-隐藏或者不显示通知”，会影响锁屏状态下离线推送通知显示。
• “手机设置-通知-更多通知设置-状态栏显示通知图标”，会影响状态栏下离线推送通知的图标显示。
• “手机设置-通知-应用的通知管理-允许通知”，打开关闭会直接影响离线推送通知显示。
• “手机设置-通知-应用的通知管理-通知铃声” 和 “手机设置-通知-应用的通知管理-静默通知”，会影响离线推送通知铃音的效果。

  厂商推送限制

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

技术咨询

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