uni-app (客户端)

最近更新时间:2025-02-26 14:16:12

我的收藏
本文档将详细介绍如何结合 TUICallKit 组件和 uni-app 腾讯云推送服务(Push),以实现音视频通话的离线推送能力。
应用在后台或离线时通知 (海外)
应用在后台或离线时通知 (国内)
锁屏时通知 (国内)






步骤一:厂商配置

uniapp 厂商配置包含 Android 厂商配置 和 iOS 厂商配置, 详细参见 厂商配置 - uniapp

步骤二:下载 Push 插件并导入 Hbuilderx

说明:
HBuilderX 4.29 有 bug,请使用 HBuilderX 4.36 或更高版本,并升级 uni-app 腾讯云推送服务(Push)到 1.1.0 或更高版本。
1. 打开 uni-app 腾讯云推送服务(Push),单击下载插件并导入 HbuilderX,将插件导入 HbuilderX 工程中。

2. 选择需要集成的工程并单击确定

3. 集成后效果如下图所示:




步骤三:离线推送配置

说明:
HBuilderX 4.36 发布了不向下兼容的更新,如果您使用的是 HBuilderX 4.36 或者更高版本,且需要 vivo/荣耀 的厂商推送,请升级 uni-app 腾讯云推送服务(Push)版本到 1.1.0 或更高版本,并参考文档正确配置 manifestPlaceholders.jsonmcs-services.json
您需在 nativeResources 目录下进行推送配置。若项目根目录尚未创建该文件夹,请新建一个名为 nativeResources 的文件夹。
确保您用 HBuilderX 打开的项目中 nativeResources 目录存在,且与 uni_modules 目录平级。
Android
iOS
1. 新建 nativeResources/android/assets 目录。
2. 配置 timpush-configs.json(在 推送服务 Push > 接入设置 > 一键式快速配置 下载),到 nativeResources/android/assets/ 目录下。如图所示:


3. 华为、荣耀、vivo、FCM。
FCM
华为
荣耀
vivo
您需要支持 FCM 推送时,需要配置 google services。
1. 配置 com.google.gms.google-servicesuni_modules/TencentCloud-Push/app-android/config.json project.plugin 中,如下所示:
"project": {
"plugins": [
...
"com.google.gms.google-services"
],
"dependencies": [
"com.huawei.agconnect:agcp:1.9.1.301",
"com.google.gms:google-services:4.3.15",
"com.hihonor.mcs:asplugin:2.0.1.300"
]
}

2. 配置 google-services.json 文件到 nativeResources/android/ 目录下。如图所示:

您需要支持华为推送时,需要配置agconnect-services.json (此文件获取详见 厂商配置 > uniapp > 华为 > 步骤4:获取应用信息)到 nativeResources/android/assets/ 目录下。如图所示:

1. 编辑 uni_modules/TencentCloud-Push/utssdk/app-android/config.jsondependencies,添加 "com.tencent.timpush:honor:8.3.6498"
{
...
"dependencies": [
...
"com.tencent.timpush:honor:8.3.6498"
]
}
2. 配置 mcs-services.json 文件到 nativeResources/android (此文件获取详见 厂商配置 > uniapp > 荣耀 > 步骤3.2:进入应用详情, 绑定应用包名,下载 mcs-services.json 文件)目录下。如图所示:



3. 配置 appIDnativeResources/android/manifestPlaceholders.json 中的 "HONOR_APPID"



{
"HONOR_APPID": ""
}
1. 编辑 uni_modules/TencentCloud-Push/utssdk/app-android/config.jsondependencies,添加 "com.tencent.timpush:vivo:8.3.6498"
{
...
"dependencies": [
...
"com.tencent.timpush:vivo:8.3.6498"
]
}
2. 配置 appIDappKeynativeResources/android/manifestPlaceholders.json 中的 VIVO_APPKEYVIVO_APPID



{
"VIVO_APPKEY": "",
"VIVO_APPID": "",
}
1. 新建 nativeResources/ios/Resources 目录。
2. nativeResources/ios/Resources新建 timpush-configs.json 文件。
3. 并将在 IM控制台 > 推送服务 Push > 接入设置 获取的证书ID,补充到 timpush-configs.json 文件中。如下所示:
{
"businessID":"xxx"
}


步骤四:引入并注册腾讯云推送服务(Push)

将 SDKAppID 和 appKey 替换为您在 IM 控制台 - 推送服务 Push - 接入设置页面 获取的应用的信息。如图所示:



// 集成 TencentCloud-Push
import * as Push from '@/uni_modules/TencentCloud-Push';
const SDKAppID = 0; // 您的 SDKAppID
const appKey = ''; // 客户端密钥
const userID = 'xx'; // 您的登录 userID

Push.setRegistrationID(userID, (res) => {
console.log('setRegistrationID OK', res);
});
Push.registerPush(SDKAppID, appKey, (data) => {
console.log('registerPush ok', data);
Push.getRegistrationID((registrationID) => {
console.log('getRegistrationID ok', registrationID);
});
}, (errCode, errMsg) => {
console.error('registerPush failed', errCode, errMsg);
}
);

// 监听通知栏点击事件,获取推送扩展信息
Push.addPushListener(Push.EVENT.NOTIFICATION_CLICKED, (res) => {
// res 为推送扩展信息
console.log('notification clicked', res);
});

// 监听在线推送
Push.addPushListener(Push.EVENT.MESSAGE_RECEIVED, (res) => {
// res 为消息内容
console.log('message received', res);
});

// 监听在线推送被撤回
Push.addPushListener(Push.EVENT.MESSAGE_REVOKED, (res) => {
// res 为被撤回的消息 ID
console.log('message revoked', res);
});

步骤五:使用云端证书,生成自定义基座

单击 HBuilderX 的运行 > 运行到手机或模拟器 > 制作自定义调试基座,使用云端证书制作 Android 或 iOS 自定义调试基座。



步骤六:体验您的第一次推送





高级功能

获取离线推送扩展信息

App.vue 内处理 onShow 回调,当设备收到离线推送,拉起 app 时,业务侧可通过 getNotificationExtInfo 接口获取推送扩展信息。
export default {
onLaunch: function() {
},
onShow: function() {
console.log('App Show')
Push.getNotificationExtInfo((extInfo) => {
console.log('getNotificationExtInfo ok', extInfo);
})
},
onHide: function() {
console.log('App Hide')
}
}

自定义推送内容

在调用 calls 发起通话时,可通过 offlinePushInfo 字段来自定义对端收到推送时的内容。



CallKit 单独集成场景
Chat + Call 融合场景
uni-app(客户端)
Web/小程序
// https://cloud.tencent.com/document/product/647/78763#calls
const callParams = {
userIDList: ['user1'],
callMediaType: 1,
callParams: {
offlinePushInfo: {
title: "test-title", // 修改 title
description: "you have a call", // 修改 discription
}
},
};

uni.$TUICallKit.calls(callParams, res => {} );
// https://cloud.tencent.com/document/product/647/81015#calls
await TUICallKitServer.calls({
userIDList: ['mike'],
type: TUICallType.VIDEO_CALL,
offlinePushInfo: {
title: "test-title", // 修改 title
description: "you have a call", // 修改 discription
}
});
修改 callOfflinePushInfo 对象中的参数。




自定义推送铃声

说明:
发送端 @tencentcloud/chat ≥ 3.3.2
支持华为、小米、OPPO、FCM 和 APNS,更详细配置参考 Push-自定义铃音

接收端

Android
iOS
定制的铃音资源文件,添加到项目 nativeResources/android/res/raw 目录下,如图所示:



设置私信通道和自定义铃音( OPPO、FCM 需要设置)
说明:
1. uni-app 腾讯云推送服务(Push) ≥ 0.5.0。
2. OPPO、FCM 使用自定义铃音需要先设置私信通道和自定义铃音。
完上述步骤后,您可以调用 push.createNotificationChannel 设置 OPPO 、FCM 私信通道和自定义铃音。
App.vue 中设置 OPPO、FCM 私信通道。如图所示:
import * as Push from '@/uni_modules/TencentCloud-Push';
Push.createNotificationChannel({
channelID: '', // 自定义 channel 的 ID。OPPO 为控制台配置的 channelID
channelName: '自定义channel',// 自定义channel 名称
channelDesc: '这只是描述', // 自定义 channel 描述
channelSound: 'private_ring' // 自定义铃音的名称且不需要后缀名
}, () => {
console.log('Push | createNotificationChannel ok');
})
说明:
iOS 自定义铃音,uni-app 必须为正式包。
iOS 自定义铃音长度不能超过 30s。
定制的铃音资源文件,添加到项目 nativeResources/ios/Resources 目录下,如图所示:




发送端

1. 升级 @tencentcloud/chat 到最新版本。
npm install @tencentcloud/chat@latest
web
uniapp
小程序
在浏览器控制台查看 TencentCloudChat.VERSION 版本号,来确认 @tencentcloud/chat ≥ 3.3.2 如图所示:

在 HBuilder 日志中查看 TencentCloudChat.VERSION 版本号,来确认 @tencentcloud/chat ≥ 3.3.2 如图所示:

在小程序开发者工具控制台查看 TencentCloudChat.VERSION 版本号,来确认 @tencentcloud/chat ≥ 3.3.2 如图所示:

2. 发送消息,设置 offlinePushInfo 自定义铃音的相关参数。
说明:
小米手机在 Android 8.0 及以上版本必须设置 androidInfo.XiaoMiChannelID,请您参见:小米自定义铃声
谷歌手机 FCM 推送在 Android 8.0 及以上系统设置声音提示,必须设置 androidInfo.FCMChannelID。
TUICallKit 单独集成场景
TUIKit + TUICallKit 融合场景
说明:
androidSound 为铃声文件名,不需要后缀名。
iOSSound 为铃声文件名,需要后缀名。
uni-app(客户端)
Web/小程序
const callParams = {
userIDList: ['user1'],
callMediaType: 1, // 语音通话(callMediaType = 1)、视频通话(callMediaType = 2)
callParams: {
offlinePushInfo: {
title: "test-title",
description: "you have a call",
androidSound: 'private_ring', // androidSound 为铃声文件名,不需要后缀名
iOSSound: 'private_ring.mp3', // iOSSound为铃声文件名,需要后缀名
}
},
};

uni.$TUICallKit.calls(callParams, res => {} );
// https://cloud.tencent.com/document/product/647/81015#calls
await TUICallKitServer.calls({
userIDList: ['mike'],
type: TUICallType.VIDEO_CALL,
offlinePushInfo: {
title: 'xxx',
androidSound: 'private_ring', // androidSound 为铃声文件名,不需要后缀名
iOSSound: 'private_ring.mp3', // iOSSound为铃声文件名,需要后缀名
}
});
说明:
androidSound 为铃声文件名,不需要后缀名。
iOSSound 为铃声文件名,需要后缀名。
修改 callOfflinePushInfo 对象中的参数。





推送结果回调

开启推送服务后,推送结果可以通过配置基础回调的方式,将结果转发给 App 后台,详见:

常见问题

设备通知栏如何设置?

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

“手机设置-通知-应用的通知管理-通知铃声” 和 “手机设置-通知-应用的通知管理-静默通知”,会影响推送通知铃音的效果。

厂商推送限制如何设置?

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

技术咨询

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