二、通道支持说明
由于不同手机系统的限制，仅部分通道支持自定义铃声功能，支持情况如下：
| 厂商 | 是否支持自定义铃音 |
| iOS | 支持 |
| 华为 | 支持 |
| 荣耀 | 跟随系统默认通知铃音 |
| 小米 | 支持 |
| vivo | 跟随系统默认通知铃音 |
| OPPO | 支持 |
| 魅族 | 跟随系统默认通知铃音 |
| FCM | 支持 |
三、各端功能实现
AndroidiOSFlutteruni-appReact Native微信小程序多端框架HarmonyOS
四、Android 8.0 以下系统
1. 定制的铃音资源文件，Android 添加到工程 raw 目录下，iOS 链接进 Xcode 工程。
2. 发送消息指定生效自定义铃音。
REST APISDK API请参考 REST API 接口，比如 单发推送接口，字段示例如下： { // … "OfflinePushInfo": { "AndroidInfo": { "Sound": "shake" // 不带后缀 }, "ApnsInfo": { "Sound": "apns.caf", } }} 若集成了 IM 相关产品，请你发送消息调用接口 setAndroidSound() 和 setIOSSound()。V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();v2TIMOfflinePushInfo.setAndroidSound("铃音名称");v2TIMOfflinePushInfo.setIOSSound("铃音名称.mp3");String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null, V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {@Override public void onProgress(int progress) { }@Override public void onError(int code, String desc) { }@Override public void onSuccess(V2TIMMessage v2TIMMessage) { }});
六、华为和 APNS
华为、APNS 可调用上面接口来设置离线推送铃音提示。
七、OPPO
1. 将定制的铃音资源文件放在工程资源的 raw 目录下，然后通过以下方式创建通知 channel。
// 自定义创建示例if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { NotificationManager nm = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE); NotificationChannel notificationChannel = new NotificationChannel("channelId", "channelName", NotificationManager.IMPORTANCE_HIGH); notificationChannel.enableLights(true); notificationChannel.enableVibration(true); notificationChannel.setShowBadge(true); notificationChannel.setLockscreenVisibility(Notification.VISIBILITY_PUBLIC); // "android.resource://包名/raw/private_ring" notificationChannel.setSound(Uri.parse("sound"), null); nm.createNotificationChannel(notificationChannel);}
2. 使用创建的 channel。
·创建私信通道。
·发送消息指定 channelID 生效自定义铃音，接口设置参考如下，控制台设置见证书的 channelID 字段，两者设置一个即可。
REST APISDK API请参考 REST API 接口，比如 单发推送接口，字段示例如下： { // … "OfflinePushInfo": { "AndroidInfo": { "OPPOChannelID": "test_OPPO_channel_id" } }} 若集成了 IM 相关产品，请你发送消息调用接口 setAndroidOPPOChannelID。
八、小米
1. 登录厂商控制台 创建 channel 和配置，其中铃音文件需要添加到你本地 Android Studio 工程的 raw 目录下，url 填写示例：“android.resource://com.tencent.timpush/raw/ring”
2. 发送消息指定 channelID 生效自定义铃音，接口设置参考如下，控制台设置见证书的 channelID 字段，两者设置一个即可。
REST APISDK API请参考 REST API 接口，比如 单发推送接口，字段示例如下： { // … "OfflinePushInfo": { "AndroidInfo": { "XiaoMiChannelID": "test_XiaoMi_channel_id" } }} 若集成了 IM 相关产品，详情请参见 setAndroidXiaoMiChannelID。V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();v2TIMOfflinePushInfo.setAndroidXiaoMiChannelID("厂商申请的 channel ID");String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null, V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {@Override public void onProgress(int progress) { TUIChatUtils.callbackOnProgress(callBack, progress); }@Override public void onError(int code, String desc) { TUIChatUtils.callbackOnError(callBack, TAG, code, desc); }@Override public void onSuccess(V2TIMMessage v2TIMMessage) { }});
九、FCM
1.1 1 将定制的铃音资源文件放在工程资源的 raw 目录下，然后通过以下方式创建通知 channel。
// 自定义创建示例if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { NotificationManager nm = (NotificationManager) context.getSystemService(context.NOTIFICATION_SERVICE); NotificationChannel notificationChannel = new NotificationChannel("channelId", "channelName", NotificationManager.IMPORTANCE_HIGH); notificationChannel.enableLights(true); notificationChannel.enableVibration(true); notificationChannel.setShowBadge(true); notificationChannel.setLockscreenVisibility(Notification.VISIBILITY_PUBLIC); // "android.resource://包名/raw/private_ring" notificationChannel.setSound(Uri.parse("sound"), null); nm.createNotificationChannel(notificationChannel);}
2 发送消息指定自定义铃音的 channelID，
REST APISDK API请参考 REST API 接口，比如 单发推送接口，字段示例如下： { // … "OfflinePushInfo": { "AndroidInfo": { "GoogleChannelID": "test_Google_channel_id", } }} 若集成了 IM 相关产品，详情请参见 setAndroidFCMChannelID。V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();v2TIMOfflinePushInfo.setAndroidFCMChannelID(PrivateConstants.fcmPushChannelId);String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null, V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {@Override public void onProgress(int progress) { TUIChatUtils.callbackOnProgress(callBack, progress); }@Override public void onError(int code, String desc) { TUIChatUtils.callbackOnError(callBack, TAG, code, desc); }@Override public void onSuccess(V2TIMMessage v2TIMMessage) { }});
1. 请在发送消息的时候设置 OfflinePushInfo 的 iOSSound 字段， iOSSound 传语音文件名。
REST APISDK API请参考 REST API 接口，比如 单发推送接口，字段示例如下： { // … "OfflinePushInfo": { "ApnsInfo": { "Sound": "apns.caf" } }} 若集成了 IM 相关产品，请你发送消息参考：V2TIMOfflinePushInfo *pushInfo = [[V2TIMOfflinePushInfo alloc] init];pushInfo.title = @"push title";pushInfo.iOSSound = @"phone_ringing.caf"; // your voice file's name[[V2TIMManager sharedInstance] sendMessage:msg receiver:receiver groupID:groupID priority:V2TIM_PRIORITY_DEFAULT onlineUserOnly:NO offlinePushInfo:pushInfo progress:nil succ:^{} fail:^(int code, NSString *msg) {}];
注意：说明：
2. 请在发送消息的时候设置 OfflinePushInfo 的 AndroidSound 字段， AndroidSound 传语音文件名。
REST APISDK API请参考 REST API 接口，比如 单发推送接口，字段示例如下： { "OfflinePushInfo": { "AndroidInfo": { "Sound": "shake", // 不带后缀 "XiaoMiChannelID": "test_XiaoMi_channel_id", "OPPOChannelID": "test_OPPO_channel_id", "GoogleChannelID": "test_Google_channel_id" }, "ApnsInfo": { "Sound": "apns.caf" } }} 若集成了 IM 相关产品，请你发送消息参考：V2TIMOfflinePushInfo *pushInfo = [[V2TIMOfflinePushInfo alloc] init];pushInfo.title = @"push title";pushInfo.AndroidSound = @"phone_ringing"; // your voice file's name[[V2TIMManager sharedInstance] sendMessage:msg receiver:receiver groupID:groupID priority:V2TIM_PRIORITY_DEFAULT onlineUserOnly:NO offlinePushInfo:pushInfo progress:nil succ:^{} fail:^(int code, NSString *msg) {}];
注意：说明：
注意：接口支持华为、小米、FCM 和 APNS。定制的铃音资源文件，Android 添加到工程 raw 目录下，iOS 链接进 Xcode 工程。请在发送消息的时候设置 offlinePushInfo 的 iOSSound 及 androidSound 字段。REST APISDK API请参考 REST API 接口，例如 单发推送接口，字段示例如下： { // … "OfflinePushInfo": { "AndroidInfo": { "Sound": "shake", // 不带后缀 "XiaoMiChannelID": "test_XiaoMi_channel_id", "OPPOChannelID": "test_OPPO_channel_id", "GoogleChannelID": "test_Google_channel_id" }, "ApnsInfo": { "Sound": "apns.caf" } }} 若集成了 IM 相关产品，请在调用 sendMessage 发送消息的时候设置 offlinePushInfo 的 iOSSound 及 androidSound 字段。具体各厂商配置，请参阅 Android 及 iOS 模块的内容。调用的方法均在 Flutter 版本的 IM SDK 中有同名方法。
注意：说明：
十、接收端
AndroidiOS
定制的铃音资源文件，添加到项目 nativeResources/android/res/raw 目录下：
十一、设置私信通道和自定义铃音（ 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');})
注意：说明：
定制的铃音资源文件，添加到项目 nativeResources/ios/Resources 目录下：
十三、1. 升级 @tencentcloud/chat 到最新版本。
npm install @tencentcloud/chat@latest
webuni-app小程序在浏览器控制台查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat ≥ 3.3.2 如下：在 HBuilder 日志中查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat ≥ 3.3.2 如下：在小程序开发者工具控制台查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat ≥ 3.3.2 如下：
十四、2. 发送消息，设置 offlinePushInfo 自定义铃音的相关参数。
注意：说明：
含 UI 集成无 UI 集成CallKit 集成
注意：说明：
在 UIKit 中使用 TUIChatService 发送消息时，设置 offlinePushInfo 相关参数，如发送普通文本消息，代码如下：
// 发送普通文本消息let promise = TUIChatService.sendTextMessage({ payload: { text: 'Hello world!' }},{ // 如果接收方不在线，则消息将存入漫游，且进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容 offlinePushInfo: { androidInfo: { // Android 推送配置 sound: 'private_ring.mp3', // Android 自定义铃音 XiaoMiChannelID: '', // 小米手机在 Android 8.0 及以上版本必须设置 XiaoMiChannelID FCMChannelID: '', // 谷歌手机 FCM 在 Android 8.0 及以上系统设置声音提示，必须设置 FCMChannelID。 OPPOChannelID: '', // OPPO手机必须设置 OPPOChannelID }, apnsInfo: { // APNs 推送配置 // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。 // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。 sound: 'private_ring.caf', // iOS 自定义铃音 } }});promise.catch((error) => { // 调用异常时业务侧可以通过 promise.catch 捕获异常进行错误处理});
参考文档：
·UIKit – TUIChatService 发送消息相关文档
注意：说明：
在 chat 发送消息时，设置 offlinePushInfo 相关字段，代码如下:
// 消息发送选项chat.sendMessage(message, { // 如果接收方不在线，则消息将存入漫游，且进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容 offlinePushInfo: { androidInfo: { // Android 推送配置 sound: 'private_ring.mp3', // Android 自定义铃音 XiaoMiChannelID: '', // 小米手机在 Android 8.0 及以上版本必须设置 XiaoMiChannelID FCMChannelID: '', // 谷歌手机 FCM 在 Android 8.0 及以上系统设置声音提示，必须设置 FCMChannelID。 OPPOChannelID: '', // OPPO手机必须设置 OPPOChannelID }, apnsInfo: { // APNs 推送配置 // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。 // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。 sound: 'private_ring.caf', // iOS 自定义铃音 } }});
参考文档：Chat SDK – sendMessage 文档
注意：说明：
const TUICallKit = uni.requireNativePlugin('TencentCloud-TUICallKit');const options = { userID: '', callMediaType: 1, // 语音通话(callMediaType = 1)、视频通话(callMediaType = 2) callParams: { // 如果接收方不在线，进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容 offlinePushInfo: { title: 'test-title', description: 'you have a test call', androidSound: 'private_ring', // Android 离线推送的自定义铃音 iOSSound: 'private_ring.caf', // iOS 离线推送的自定义铃音 }, },};TUICallKit.call(options, (res) => { if (res.code === 0) { console.log('call success'); } else { console.log(`call failed, error message = ${res.msg}`); }});
参考文档：CallKit 配置 offlinePushInfo
注意：说明：
十五、接收端
AndroidiOS
定制的铃音资源文件，添加到项目 MyReactNativeApp/android/app/src/main/res/raw 目录下，如果该目录不存在，请手动创建。如下：
注意：说明：
注意：iOS 自定义铃音长度不能超过 30s。
定制的铃音资源文件，添加项目到 MyReactNativeApp/ios/MyReactNativeApp/Resources 目录下，并用 Xcode 打开 MyReactNativeApp 项目，右键点击项目 > Add Files to "MyReactNativeApp"，将铃音文件添加到工程。如下：
| 项目 | Xcode |
| | |
十六、发送端
发送消息，设置 offlinePushInfo 自定义铃音的相关参数。
注意：说明：
// 消息发送选项chat.sendMessage(message, { // 如果接收方不在线，则消息将存入漫游，且进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容 offlinePushInfo: { androidInfo: { // Android 推送配置 sound: 'private_ring.mp3', // Android 自定义铃音 XiaoMiChannelID: '', // 小米手机在 Android 8.0 及以上版本必须设置 XiaoMiChannelID FCMChannelID: '', // 谷歌手机 FCM 在 Android 8.0 及以上系统设置声音提示，必须设置 FCMChannelID。 OPPOChannelID: '', // OPPO手机必须设置 OPPOChannelID }, apnsInfo: { // APNs 推送配置 // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。 // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。 sound: 'private_ring.caf', // iOS 自定义铃音 } }});
参考文档：Chat SDK > sendMessage 文档
十七、客户端配置
AndroidiOS
注意：说明：
注意：配置原生资源请参考文档。
十八、1、添加自定义铃音文件
把铃音文件添加到项目 miniapp/android/nativeResources/res/raw 目录下：
20、2、创建客户端通知 channel
在 App 启动时调用 Push.createNotificationChannel 方法设置通知 channel。
import Push from "@tencentcloud/donut-push"App({ onLaunch: function () { Push.createNotificationChannel({ channelID: "", // 自定义 channel 的 ID。 channelName: "", // 自定义channel 名称 channelDesc: "", // 自定义 channel 描述 channelSound: "" // 自定义铃音文件的名称且不需要文件扩展名 }).then((ret) => { console.info("createNotificationChannel success", ret); }).catch((ret) => { console.error("createNotificationChannel failed", ret); }); }})
注意：说明：
21、1、添加自定义铃音文件
把铃音文件添加到项目目录下：
25、请求包示例
{ "From_Account": "administrator", "To_Account": ["100480"], "MsgRandom": 3674128, "OfflinePushInfo": { "PushFlag": 0, "Title": "离线推送标题1adad1", "Desc": "离线推送内容11adasd1", "Ext":"{\\"aa\\":12123}", "AndroidInfo": { "Sound": "private_ring123", // 跟客户端创建的 channel 中的铃声文件名称一致 "OPPOChannelID": "test_oppo_channel_id", "XiaoMiChannelID": "test_xiaomi_channel_id", "GoogleChannelID": "test_google_channel_id" }, "ApnsInfo": { "Sound": "01.caf"// 跟接收端 ipa 包内的铃声文件名称一致 } }}
27、配置完成后，收到推送但是手机没有铃声？
请先检查是否开启手机系统铃声，再检查 App 的通知权限中是否打开铃声开关。
28、部分手机离线推送自定义铃音设置无效？
目前支持离线推送自定义铃音的厂商有：华为、OPPO、小米、FCM、APNS。
29、接收端
注意：说明：
30、添加自定义铃音资源文件
将定制的铃音资源文件（支持 MP3、WAV、MPEG 格式）放置到应用的 /resources/rawfile/ 路径下。例如放入 private_ring.mp3：
entry/└── src/ └── main/ └── resources/ └── rawfile/ └── private_ring.mp3
32、REST API
请参考 REST API 接口，例如 单发推送接口，鸿蒙端通过 OfflinePushInfo.HarmonyInfo 字段下发铃音参数，示例如下：
{ "OfflinePushInfo": { "HarmonyInfo": { "sound":"private_ring.mp3", "soundDuration":10 } }}
33、SDK API
若集成了 IM 相关产品，请在发送消息时设置 V2TIMOfflinePushInfo 的 vendorParams 字段，将 harmonySound 和 harmonySoundDuration 拼接为 JSON 字符串传入：
import { V2TIMManager, V2TIMOfflinePushInfo } from '@tencentcloud/imsdk';const pushInfo: V2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();pushInfo.title = 'push title';pushInfo.desc = 'push desc';pushInfo.vendorParams = JSON.stringify({ harmonySound: 'private_ring.mp3', // 铃音文件名，需带后缀，与 rawfile 下的文件名保持一致 harmonySoundDuration: 10 // 铃音播放时长，单位：秒});V2TIMManager.getMessageManager().sendMessage(message, { receiver: userID, groupID: groupID, priority: V2TIMMessagePriority.V2TIM_PRIORITY_DEFAULT, onlineUserOnly: false, offlinePushInfo: pushInfo}).then(() => { console.log('sendMessage success');}).catch((err: Error) => { console.log('sendMessage failed', err.message);});