资源 | 用途 |
SDKAppID、客户端密钥(Push Key) | 调用 registerPush |
timpush-configs.json | 放入 Android 应用模块 assets |
目标厂商配置文件(如有) | Google FCM 等按厂商要求放入工程 |
工程 applicationId | 与厂商平台应用包名一致 |
TIMPush 版本号 VERSION |
资源 | 用途 |
SDKAppID、Push Key | 调用 registerPush |
证书 ID( businessID / apnsCertificateID) | 控制台上传 APNs 证书后生成,经 registerPush 传入 |
App Group ID(可选) | 仅触达统计需要,经 registerPush 的 applicationGroupID 传入 |
VERSION、SDKAppID、AppKey、证书 ID、App Group ID 均为占位符,请勿在代码仓库中提交真实密钥。pubspec.yaml 中添加依赖,也可以执行以下命令自动安装:flutter pub add tencent_cloud_chat_push
com.tencent.timpush:timpush / tuicore。只需按需引入目标厂商通道包。TencentCloudChatPushApplication。android/app/build.gradle 或 android/app/build.gradle.kts 按需引入目标厂商的 TIMPush 通道包。只有引入对应厂商包,才能启用该厂商的原生推送能力。VERSION 请前往 更新日志 获取并替换为实际版本号。dependencies {implementation 'com.tencent.timpush:fcm:VERSION'}
dependencies {implementation("com.tencent.timpush:fcm:VERSION")}
Application 类,并继承 TencentCloudChatPushApplication。如果工程中已存在自定义 Application,直接改为继承该类,并确保 onCreate() 中调用 super.onCreate()。package com.example.pushdemoimport com.tencent.chat.flutter.push.tencent_cloud_chat_push.application.TencentCloudChatPushApplicationclass MyApplication : TencentCloudChatPushApplication() {override fun onCreate() {super.onCreate()}}
android/app/src/main/AndroidManifest.xml 的 <application> 标签中配置 android:name,指向上述自定义 Application 类。<applicationandroid:name=".MyApplication"...></application>
ios/Runner/AppDelegate.swift 中补充 TIMPush 相关配置,用于返回推送证书 ID、App Group ID,以及转发离线推送点击事件。证书 ID 与 App Group ID 由 registerPush 传入,再经下列桥接方法返回给 TIMPush。import UIKitimport Flutter// Add these two import linesimport TIMPushimport tencent_cloud_chat_push// Add `, TIMPushDelegate` to the following line@UIApplicationMain@objc class AppDelegate: FlutterAppDelegate, TIMPushDelegate {override func application(_ application: UIApplication,didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {GeneratedPluginRegistrant.register(with: self)return super.application(application, didFinishLaunchingWithOptions: launchOptions)}// Add this function@objc func businessID() -> Int32 {return TencentCloudChatPushFlutterModal.shared.businessID();}// Add this function@objc func applicationGroupID() -> String {return TencentCloudChatPushFlutterModal.shared.applicationGroupID()}// Add this function@objc func onRemoteNotificationReceived(_ notice: String?) -> Bool {TencentCloudChatPushPlugin.shared.tryNotifyDartOnNotificationClickEvent(notice)return true}}
registrationID;服务端、控制台接入测试和排查工具可以使用该标识向这台设备下发离线推送。若 App 同时接入 Chat 并完成登录,也可以使用 userID 向该用户已建立推送关系的设备下发离线推送。appKey 的取值会影响注册方式和可用的推送标识:appKey = Push Key:注册 TIMPush 独立推送能力。Push Key 客户端密钥。appKey = null:复用 Chat 登录态注册推送,必须在 Chat login 成功后调用。userID 与 registrationID 推送关系都会失效,需要重新完成对应注册。registerPush 的 appKey。main 方法中调用。建议在用户同意隐私政策后,并在业务侧合适时机调用。Future<void> registerTIMPush() async {final push = TencentCloudChatPush();final registerRes = await push.registerPush(// TODO: 替换为您的 SDKAppID。sdkAppId: 0,// TODO: 替换为 Push 客户端密钥。appKey: '<#YOUR_PUSH_APP_KEY#>',// iOS:替换为在腾讯云控制台生成的证书 ID;Android 不用传。apnsCertificateID: 0,// iOS 可选:如需统计推送触达,请替换为 Apple Developer Center 或 Xcode 中配置的 App Group ID;Android 不用传。// applicationGroupID: 'group.<#YOUR_APP_GROUP_ID#>',// 当前 Flutter API 仍要求传入该参数,但该回调待废弃。// 请不要在这里处理通知点击,统一使用 addPushListener。onNotificationClicked:({required String ext, String? userID, String? groupID}) {},);if (registerRes.code != 0) {debugPrint('registerPush failed: code=${registerRes.code}, ''msg=${registerRes.errorMessage}, deviceToken=${registerRes.data}',);return;}final ridRes = await push.getRegistrationID();debugPrint('registerPush success, registrationID=${ridRes.data}, ''code=${ridRes.code}, msg=${ridRes.errorMessage}',);}
Future<void> loginIMAndRegisterPush() async {final int sdkAppId = 0; // TODO: 替换为您的 SDKAppID。final String userID = '<#YOUR_USER_ID#>';final String userSig = '<#YOUR_USER_SIG#>';final initRes = await TencentImSDKPlugin.v2TIMManager.initSDK(sdkAppID: sdkAppId,);if (initRes.code != 0) {debugPrint('initSDK failed: code=${initRes.code}, desc=${initRes.desc}');return;}final loginRes = await TencentImSDKPlugin.v2TIMManager.login(userID: userID,userSig: userSig,);if (loginRes.code != 0) {debugPrint('login failed: code=${loginRes.code}, desc=${loginRes.desc}');return;}final push = TencentCloudChatPush();final registerRes = await push.registerPush(sdkAppId: sdkAppId,// iOS:替换为在腾讯云控制台生成的证书 ID;Android 不用传。apnsCertificateID: 0,// iOS 可选:如需统计推送触达,请替换为 Apple Developer Center 或 Xcode 中配置的 App Group ID;Android 不用传。// applicationGroupID: 'group.<#YOUR_APP_GROUP_ID#>',// 当前 Flutter API 仍要求传入该参数,但该回调待废弃。// 请不要在这里处理通知点击,后续章节会介绍推荐的监听方式。onNotificationClicked:({required String ext, String? userID, String? groupID}) {},);if (registerRes.code != 0) {debugPrint('registerPush failed: code=${registerRes.code}, ''msg=${registerRes.errorMessage}, deviceToken=${registerRes.data}',);return;}final ridRes = await push.getRegistrationID();debugPrint('registerPush after login success, registrationID=${ridRes.data}, ''code=${ridRes.code}, msg=${ridRes.errorMessage}',);}
registerPush。否则 SDK 可能会按独立推送场景注册 Push 类型账号,并产生对应的 Push DAU。Push DAU 超出套餐额度后,可能会产生额外费用。registerPush 时传入 applicationGroupID。ios/Runner/AppDelegate.swift 中已实现 applicationGroupID()。TIMPush 关键字查看注册日志。注册成功后,调用 getRegistrationID() 获取当前设备推送标识。控制台或服务端发送测试消息时,可使用该值定位设备。registrationID 或 userID 发送离线推送测试。Future<void> sendTestPushMessage({required String targetUserID,}) async {final createRes = await TencentImSDKPlugin.v2TIMManager.v2TIMMessageManager.createTextMessage(text: 'Hello TIMPush');final message = createRes.data?.messageInfo;if (createRes.code != 0 || message == null) {debugPrint('createTextMessage failed: code=${createRes.code}');return;}final sendRes = await TencentImSDKPlugin.v2TIMManager.v2TIMMessageManager.sendMessage(message: message,receiver: targetUserID,groupID: '',priority: MessagePriorityEnum.V2TIM_PRIORITY_NORMAL,onlineUserOnly: false,offlinePushInfo: OfflinePushInfo(title: '推送标题',desc: '推送内容',ext: '{"action":"open_chat","conversationID":"c2c_$targetUserID"}',),);debugPrint('sendMessage result: code=${sendRes.code}, desc=${sendRes.desc}, ''msgID=${sendRes.data?.msgID}',);}
extOfflinePushInfo.ext 携带跳转参数。示例代码如下:Future<void> sendMessageWithPushExt({required String targetUserID,}) async {final createRes = await TencentImSDKPlugin.v2TIMManager.v2TIMMessageManager.createTextMessage(text: 'Hello TIMPush');final message = createRes.data?.messageInfo;if (createRes.code != 0 || message == null) {debugPrint('createTextMessage failed: code=${createRes.code}');return;}final sendRes = await TencentImSDKPlugin.v2TIMManager.v2TIMMessageManager.sendMessage(message: message,receiver: targetUserID,groupID: '',priority: MessagePriorityEnum.V2TIM_PRIORITY_NORMAL,onlineUserOnly: false,offlinePushInfo: OfflinePushInfo(title: '推送标题',desc: '推送内容',ext: '{"conversationID":"$targetUserID","conversationType":1}',),);debugPrint('sendMessage result: code=${sendRes.code}, desc=${sendRes.desc}, ''msgID=${sendRes.data?.msgID}',);}
extTencentCloudChatPush().addPushListener 监听通知点击事件,并在 onNotificationClicked 中解析 ext。示例代码如下:final TIMPushListener timPushListener = TIMPushListener(onRecvPushMessage: (TimPushMessage msg) {debugPrint('onRecvPushMessage: title=${msg.title}, desc=${msg.desc}, ''ext=${msg.ext}, msgID=${msg.messageID}',);},onRevokePushMessage: (String msgID) {debugPrint('onRevokePushMessage: msgID=$msgID');},onNotificationClicked: (String ext) {debugPrint('onNotificationClicked: ext=$ext');// 1. 解析 ext。JSON 结构由业务自定义,需与发送端约定一致。Map<String, dynamic>? extJson;try {extJson = jsonDecode(ext) as Map<String, dynamic>;} catch (e) {debugPrint('parse ext failed: $e');return;}final String? conversationID = extJson['conversationID'] as String?;final int? conversationType = extJson['conversationType'] as int?;if (conversationID == null || conversationType == null) {return;}// 2. TODO: 根据业务字段跳转到目标页面。// 若使用了 Chat / TUIKit,建议在用户登录成功后再跳转;// 冷启动场景可先把参数缓存起来,登录回调中再跳转。},);Future<void> addTIMPushListener() async {await TencentCloudChatPush().addPushListener(listener: timPushListener);}Future<void> removeTIMPushListener() async {await TencentCloudChatPush().removePushListener(listener: timPushListener);}
TencentCloudChatPush().registerPush 当前仍要求传入 onNotificationClicked 参数,但该参数待废弃。新接入业务请不要在 registerPush 的 onNotificationClicked 中处理跳转,统一使用 addPushListener。ext 是发送方写入的业务透传字段,建议使用 JSON 字符串,例如 {"conversationID":"user_A","conversationType":1}。listener,例如在登录流程完成后、业务首页初始化前完成注册。文档反馈