效果展示
Android(FCM) | iOS(APNs) |
![]() | ![]() |
开通服务

集成建议 [必看]
如何选择推送渠道?
由于 FCM 依赖于 Google 服务,请根据您的业务运营区域选择合适的集成策略:
跨国全球业务(涉及国内外):为确保全球范围内消息的触达率,建议同时集成国内各厂商推送服务以及 FCM 推送服务。
仅限海外市场(不涉及中国大陆):无需集成国内厂商服务。请直接参考本文档集成 FCM Data Message 即可。
仅限中国大陆境内:无需集成 FCM。请参考集成 Notification,按需集成 Notification (小米、华为、OPPO、vivo 等国内厂商) 推送即可。
如何提高推送触达率?
根据我们的经验,超过 90% 的用户接不到通话通知的原因是手动关闭了应用的通知权限。为确保通话可达率,我们强烈建议:
1. 审慎发送通知:避免向用户推送低质量或无关联的通知,减少用户因骚扰而关闭通知权限的可能性。
2. 提供精细控制:借鉴微信等优秀应用的做法,在应用设置内为用户提供独立的开关,分别控制 Notification 和 FCM Data Message,而非引导用户去系统设置中一刀切地关闭所有通知。

通用配置
flutter pub add tencent_cloud_chat_push
Android 平台配置
步骤1:厂商配置
准备条件
1. 将您自己的应用注册到 FCM 推送平台,得到 AppID 和 AppKey 等参数以及
google-services.json 文件 ,来实现离线推送功能。2.
登
录 即时通信 IM 控制台,在推送管理 > 接入设置功能栏,选择 FCM,添加 FCM 的证书,其中,消息类型选择透传(数据)消息。厂商推送平台 | IM 控制台配置 |
![]() | ![]() |
下载并添加配置文件
完成控制台厂商推送信息填写后,下载并添加配置文件到工程。将下载的
timpush-configs.json 文件添加到应用模块的 assets 目录下,将 google-services.json 添加到工程 app 目录下。选择下载配置文件 timpush-configs.json | 下载文件 google-services.json | 添加到工程 |
![]() | ![]() | ![]() |
步骤2:集成 Android 推送插件
在项目的
android/app/build.gradle 文件中添加如下依赖:implementation("com.tencent.timpush:fcm:8.8.7375")
implementation "com.tencent.timpush:fcm:latest.release"
说明:
TIMPush 需要集成 IM SDK 在7.9.5666版本及以上。TIMPush 的版本号及更新信息,可以在 更新日志 中进行查询。
在
build.gradle中添加的依赖的版本需要与tencent_cloud_chat_push版本对应。步骤3:工程配置
在您项目
android/app/src/main 路径下 MainActivity 同级目录中,新建一个 Application 文件类, 例如可命名为 MyApplication。如果您已经自定义了一个 Application 类,则可直接复用,不需要再次创建。


将下列代码粘贴到该文件中, 如上图所示:
import com.tencent.chat.flutter.push.tencent_cloud_chat_push.application.TencentCloudChatPushApplication;public class MyApplication extends TencentCloudChatPushApplication {@Overridepublic void onCreate() {super.onCreate();}}
说明:
如果您已经创建了自己的 Application 为了其他用途,请直接
extends TencentCloudChatPushApplication 并保证 onCreate() 函数中,调用了 super.onCreate(); 即可。同时,您还需要修改您的 MainActivity 文件:


打开
android/app/src/main/AndroidManifest.xml 文件,为 <application> 标签,新增指定一个 android:name 参数即可,指向刚制作的自定义 Application 类。如图所示:

步骤4:完成工程配置
在项目级
build.gradle 文件的 buildscript > dependencies 下添加以下配置:buildscript {dependencies {classpath 'com.google.gms:google-services:4.3.15'}}
在项目的
app 目录下的build.gradle文件中添加下方配置:apply plugin: 'com.google.gms.google-services'
在项目的
app 目录下,找到并打开build.gradle文件,将应用包名修改为您的实际应用包名:applicationId 'com.****.callkit'
iOS 平台配置(APNs)
步骤1:厂商配置
申请 APNs 证书
开启 App 远程推送
1. 登录 苹果开发者中心 网站,单击 Certificates, Identifiers & Profiles 或者侧栏的 Certificates, IDs & Profiles,进入 Certificates, IDS & Profiles 页面。


2. 单击 Identifiers 右侧的 +。


3. 您可以参见如下步骤新建一个 AppID,或者在您原有的 AppID 上增加
Push Notification 的 Service。说明
您 App 的
Bundle ID 不能使用通配符 *,否则将无法使用远程推送服务。4. 勾选 App IDs,单击 Continue 进行下一步。


5. 选择 App,单击 Continue 进行下一步。


6. 配置
Bundle ID 等其他信息,单击 Continue 进行下一步。

7. 勾选 Push Notifications,开启远程推送服务。


生成证书
1. 选中您的 AppID,选择 Configure。


2. 可以看到在 Apple Push Notification service SSL Certificates 窗口中有两个
SSL Certificate,分别用于开发环境(Development)和生产环境(Production)的远程推送证书,如下图所示:

3.
我
们先选择开发环境(Development)的 Create Certificate,系统将提示我们需要一个 Certificate Signing Request(CSR)。

4. 在 Mac 上打开钥匙串访问工具(Keychain Access),在菜单中选择钥匙串访问 > 证书助理 > 从证书颁发机构请求证书(
Keychain Access - Certificate Assistant - Request a Certificate From a Certificate Authority)。

5. 输入用户电子邮件地址(您的邮箱)、常用名称(您的名称或公司名),选择存储到磁盘,单击继续,系统将生成一个
*.certSigningRequest 文件。

6. 返回上述 步骤3 中 Apple Developer 网站刚才的页面,单击 Choose File 上传生成的
*.certSigningRequest 文件。

7. 单击 Continue,即可生成推送证书。


8. 单击 Download 下载开发环境的
Development SSL Certificate 到本地。

9. 再次按照上述步骤1 - 8,将生产环境的
Production SSL Certificate 下载到本地。说明
生产环境的证书实际是开发(Sandbox)+生产(Production)的合并证书,可以同时作为开发环境和生产环境的证书使用。




10. 双击打开下载的开发环境和生产环境的
SSL Certificate,系统会将其导入钥匙串中。11. 打开钥匙串应用,在登录 > 我的证书,右键分别导出刚创建的开发环境(
Apple Development IOS Push Service)和生产环境(Apple Push Services)的 P12 文件。

注意:
保存
P12文件时,请务必要为其设置密码。上传证书到控制台
1. 登录 即时通信 IM 控制台。
2. 单击目标应用卡片,进入应用的基础配置页面。


3. 单击 iOS 原生离线推送设置右侧的添加证书。
4. 选择证书类型,上传 iOS 证书(.p12),设置证书密码,单击确认。


注意:
上传证书名最好使用全英文(尤其不能使用括号等特殊字符)。
上传证书需要设置密码,无密码收不到推送。
发布 App Store 的证书需要设置为生产环境,否则无法收到推送。
上传的 p12 证书必须是自己申请的真实有效的证书。
5. 待推送证书信息生成后,记录证书的 ID。


步骤2:推送参数配置
请将您在厂商配置步骤中,获取到的 iOS APNs 推送证书, 上传至 IM 控制台。
IM 控制台会为您分配一个证书 ID,见下图:

注册推送需要将此证书 ID(apnsCertificateID)传入:
TencentCloudChatPush().registerPush(apnsCertificateID: 您配置的证书 ID);
步骤3:工程配置
您可使用 Xcode 编辑,也可直接在 Visual Studio Code 或 Android Studio 中编辑。
打开
ios/Runner/AppDelegate.swift文件,将图中圈出的代码添加到文件中。具体代码位于图片下方。

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)}// To be deprecated,please use the new field businessID below.@objc func offlinePushCertificateID() -> Int32 {return TencentCloudChatPushFlutterModal.shared.offlinePushCertificateID();}// 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}}
自定义来电推送
步骤1:注册推送插件
1. 请在登录完成后, 立即注册推送插件。
调用
TencentCloudChatPush().registerPush 方法, 需传入上一步定义的点击回调函数。此外,您还可选传入
apnsCertificateID iOS 推送证书 ID 及 androidPushOEMConfig Android 推送厂商配置。此二项配置已在前序步骤指定,若无修改必要,可不再传入。TencentCloudChatPush().registerPush(onNotificationClicked: _onNotificationClicked,sdkAppId: 您的sdkAppId,appKey: "客户端密钥",apnsCertificateID: 您配置的证书 ID);
2. 实现 Android 自动登录。
FCM 的 data 模式只能将离线 App 唤醒,所以还需要您在
onAppWakeUpEvent中实现登录以及拉起 App 等操作。TencentCloudChatPush().registerOnAppWakeUpEvent(onAppWakeUpEvent: () {// TODO: 登录操作});
步骤2:自定义来电通知样式(FCM)
您可以使用第三方插件(如 flutter_local_notifications )来弹出通知,或者在原生层创建
NotificationView 来实现更加高级的通知样式。这里我们以使用 flutter_local_notifications 为主:集成插件
首先使用以下命令添加 flutter_local_notifications 插件:
flutter pub add flutter_local_notifications
弹出通知
final plugin = FlutterLocalNotificationsPlugin();const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');await plugin.initialize(const InitializationSettings(android: androidSettings));await plugin.show(0,'来电通话','XX邀请您进行视频通话',const NotificationDetails(android: AndroidNotificationDetails('call_channel','通话通知',importance: Importance.high,priority: Priority.high,),),);
步骤3:展示来电通知(FCM)
您需要监听来电事件,登录成功后(步骤1),如果有离线来电事件,CallStore 会自动补发,您可以在该事件中显示定制的推送通知(步骤2),实现方式如下:
1. 监听来电事件:订阅 onCallReceived 事件。该事件在收到来电时触发,并包含通话所需的关键信息。
2. 展示来电通知:当收到 onCallReceived 事件后,根据该事件携带的通话信息展示通知界面。在 onCallReceived 回调中,根据事件携带的通话信息,并调用自定义的推送通知(参考步骤 2)进行展示。
import 'package:atomic_x_core/atomicxcore.dart';import 'package:flutter_local_notifications/flutter_local_notifications.dart';bool isNotificationShowing = false;void showNotification() async {final plugin = FlutterLocalNotificationsPlugin();const androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');await plugin.initialize(settings: const InitializationSettings(android: androidSettings));await plugin.show(id: 0, // 通知唯一标识符title: '来电通话',body: '张三正在呼叫你',notificationDetails: const NotificationDetails(android: AndroidNotificationDetails('call_channel','通话通知',importance: Importance.high,priority: Priority.high,),),);isNotificationShowing = true;}void closeNotification() {final plugin = FlutterLocalNotificationsPlugin();plugin.cancel(id: 0, // 需要关闭的通知的唯一标识符);isNotificationShowing = false;}void _addNotificationListener() {_listener = CallEventListener(onCallReceived: (callId, mediaType, userData) {showNotification();},onCallEnded: (callId, mediaType, reason, userId) {closeNotification();},);CallStore.shared.addListener(_listener!);CallStore.shared.state.selfInfo.addListener(() {if (isNotificationShowing) {closeNotification();}});}
常见问题
应用被杀死后无法弹出来电界面?
确认收到了推送,收不到推送需要确认下 IM 控制台是否正确上传证书。参见文档上述厂商配置的第一步,看下是否添加正确。
确认控制台选择了 FCM 数据消息。
确认收到数据消息,过滤日志(关键字:TIMPush),检查下述日志是否有打印记录(如果收不到消息,可以使用 IM 控制台的 排查工具 查看原因)。


确认实现了自动登录。自动登录后才会去拉取通话请求,才能显示来电界面。
怎样强制使用 FCM 通道?
若您的业务想要强制使用 FCM 通道,可调用以下接口:
TIMPushManager.getInstance().forceUseFCMPushChannel(true);






