@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/knowledge/callkit/core-sdk/flutter/offline-push.md

@@ -0,0 +1,412 @@
+本文档将指导您如何基于 [tencent_cloud_chat_push](https://pub.dev/packages/tencent_cloud_chat_push) 插件实现离线推送功能，适用于使用 AtomicXCore 进行无 UI 集成的场景。
+
+## 效果展示
+| <strong>Android（FCM）</strong> | <strong>iOS（APNs）</strong> |
+| --- | --- |
+|  |  |
+
+## 开通服务
+
+进入 [IM 控制台 > 插件市场](https://console.cloud.tencent.com/im/plugin/TIMPush)，单击**立即购买**或**免费试用**。
+
+> **注意：**
+>
+
+> 购买及免费试用规则详见 计费说明。
+>
+
+## 集成建议 [必看]
+
+### 如何选择推送渠道？
+
+由于 FCM 依赖于 Google 服务，**请根据您的业务运营区域选择合适的集成策略**：
+- **跨国全球业务（涉及国内外）：**为确保全球范围内消息的触达率，建议同时集成国内各厂商推送服务以及 FCM 推送服务。
+
+- **仅限海外市场（不涉及中国大陆）：**无需集成国内厂商服务。请直接参考本文档集成 FCM Data Message 即可。
+
+- **仅限中国大陆境内：**无需集成 FCM。请参考集成 Notification，按需集成 **Notification **(小米、华为、OPPO、vivo 等国内厂商) 推送即可。
+
+### 如何提高推送触达率？
+
+根据我们的经验，超过 90% 的用户接不到通话通知的原因是手动关闭了应用的通知权限。为确保通话可达率，我们强烈建议：
+1. **审慎发送通知：**避免向用户推送低质量或无关联的通知，减少用户因骚扰而关闭通知权限的可能性。
+
+2. **提供精细控制：**借鉴微信等优秀应用的做法，在应用设置内为用户提供独立的开关，分别控制 Notification 和 FCM Data Message，而非引导用户去系统设置中一刀切地关闭所有通知。
+
+## 通用配置
+
+**安装组件**：在工程的根目录下，通过命令行执行以下命令安装 [tencent_cloud_chat_push](https://pub.dev/packages/tencent_cloud_chat_push) 插件。
+``` bash
+flutter pub add tencent_cloud_chat_push
+```
+
+## Android 平台配置
+
+### 步骤1：厂商配置
+
+#### 准备条件
+1. 将您自己的应用注册到 [FCM 推送平台](https://console.firebase.google.com/u/0/)，得到 **AppID** 和 **AppKey** 等参数以及 `google-services.json`文件 ，来实现离线推送功能。
+
+2.
+
+登录 [即时通信 IM 控制台](https://console.cloud.tencent.com/im)，在**推送管理** > **接入设置**功能栏，选择 FCM，添加 FCM 的证书，其中，消息类型选择**透传（数据）消息**。
+
+   |厂商推送平台|IM 控制台配置|
+   |---------|---------|
+   |||
+
+#### 下载并添加配置文件
+
+完成控制台厂商推送信息填写后，下载并添加配置文件到工程。将下载的 `timpush-configs.json` 文件添加到应用模块的 `assets` 目录下，将 `google-services.json` 添加到工程 app 目录下。
+
+|选择下载配置文件 timpush-configs.json|下载文件 google-services.json|添加到工程|
+|---------|---------|---------|
+||||
+
+### 步骤2：集成 Android 推送插件
+
+在项目的 `android/app/build.gradle` 文件中添加如下依赖：
+
+【build.gradle.kts】
+``` java
+implementation("com.tencent.timpush:fcm:8.8.7375")
+```
+
+【build.gradle】
+``` java
+implementation "com.tencent.timpush:fcm:latest.release"
+```
+
+> **说明：**
+>
+> - TIMPush 需要集成 IM SDK 在**7.9.5666**版本及以上。TIMPush 的版本号及更新信息，可以在 [更新日志](https://cloud.tencent.com/document/product/269/102807) 中进行查询。
+> - 在`build.gradle`中添加的依赖的版本需要与`tencent_cloud_chat_push`版本对应。
+
+### 步骤3：工程配置
+
+在您项目 `android/app/src/main` 路径下 `MainActivity` 同级目录中，新建一个 Application 文件类, 例如可命名为 `MyApplication`。
+
+如果您已经自定义了一个 Application 类，则可直接复用，不需要再次创建。
+
+将下列代码粘贴到该文件中, 如上图所示：
+``` java
+import com.tencent.chat.flutter.push.tencent_cloud_chat_push.application.TencentCloudChatPushApplication;
+
+public class MyApplication extends TencentCloudChatPushApplication {
+    @Override
+    public 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` 下添加以下配置：
+
+   ``` java
+   buildscript {
+       dependencies {
+           classpath 'com.google.gms:google-services:4.3.15'
+       }
+   }
+   ```
+- 在项目的 `app` 目录下的`build.gradle`文件中添加下方配置：
+
+   ``` java
+   apply plugin: 'com.google.gms.google-services'
+   ```
+- 在项目的 `app` 目录下，找到并打开`build.gradle`文件，将应用包名修改为您的实际应用包名：
+
+   ``` java
+   applicationId 'com.****.callkit'
+   ```
+
+## iOS 平台配置（APNs）
+
+### 步骤1：厂商配置
+
+#### 申请 APNs 证书
+
+##### 开启 App 远程推送
+1. 登录 [苹果开发者中心](https://developer.apple.com/account/) 网站，单击 **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 控制台](https://console.cloud.tencent.com/im)。
+
+2. 单击目标应用卡片，进入应用的基础配置页面。
+
+3. 单击 **iOS 原生离线推送设置**右侧的**添加证书**。
+
+4. 选择证书类型，上传 iOS 证书（.p12），设置证书密码，单击**确认**。
+
+   > **注意：**
+   >
+>   - 上传证书名最好使用全英文（尤其不能使用括号等特殊字符）。
+>   - 上传证书需要设置密码，无密码收不到推送。
+>   - 发布 App Store 的证书需要设置为生产环境，否则无法收到推送。
+>   - 上传的 p12 证书必须是自己申请的真实有效的证书。
+
+5. 待推送证书信息生成后，记录证书的 ID。
+
+### 步骤2：推送参数配置
+
+请将您在厂商配置步骤中，获取到的 iOS APNs 推送证书， 上传至 IM 控制台。
+
+IM 控制台会为您分配一个证书 ID，见下图：
+
+注册推送需要将此证书 ID（apnsCertificateID）传入：
+``` java
+TencentCloudChatPush().registerPush(apnsCertificateID: 您配置的证书 ID);
+```
+
+### 步骤3：工程配置
+
+您可使用 Xcode 编辑，也可直接在 Visual Studio Code 或 Android Studio 中编辑。
+
+打开 `ios/Runner/AppDelegate.swift`文件，将图中圈出的代码添加到文件中。具体代码位于图片下方。
+
+``` swift
+import UIKit
+import Flutter
+
+// Add these two import lines
+import TIMPush
+import 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 推送厂商配置。此二项配置已在前序步骤指定，若无修改必要，可不再传入。
+
+   ``` java
+   TencentCloudChatPush().registerPush(
+       onNotificationClicked: _onNotificationClicked,
+       sdkAppId: 您的sdkAppId,
+       appKey: "客户端密钥",
+       apnsCertificateID: 您配置的证书 ID);
+   ```
+2. **实现 Android 自动登录。**
+
+   FCM 的 data 模式只能将离线 App 唤醒，所以还需要您在`onAppWakeUpEvent`中实现登录以及拉起 App 等操作。
+
+   ``` java
+   TencentCloudChatPush().registerOnAppWakeUpEvent(onAppWakeUpEvent: () {
+         // TODO: 登录操作
+   });
+   ```
+
+### 步骤2：自定义来电通知样式（FCM）
+
+您可以使用第三方插件（如 flutter_local_notifications ）来弹出通知，或者在原生层创建 `NotificationView` 来实现更加高级的通知样式。这里我们以使用 flutter_local_notifications 为主：
+
+#### 集成插件
+
+首先使用以下命令添加 flutter_local_notifications 插件：
+``` bash
+flutter pub add flutter_local_notifications
+```
+
+#### 弹出通知
+``` java
+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](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/flutter/v1.0/zh/api_call_call_store/CallEventListener/onCallReceived.html) 事件。该事件在收到来电时触发，并包含通话所需的关键信息。
+
+2. **展示来电通知：**当收到 [onCallReceived](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/flutter/v1.0/zh/api_call_call_store/CallEventListener/onCallReceived.html) 事件后，根据该事件携带的通话信息展示通知界面。在 [onCallReceived](https://liteav.sdk.qcloud.com/doc/product/tuikit/atomic-x/flutter/v1.0/zh/api_call_call_store/CallEventListener/onCallReceived.html) 回调中，根据事件携带的通话信息，并调用自定义的推送通知（参考步骤 2）进行展示。
+
+   ``` java
+   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();
+       }
+     });
+   }
+   ```
+
+## 常见问题
+
+若在集成过程中遇到问题，请务必先查阅 [插件推送 > 常见问题](https://cloud.tencent.com/document/product/269/100650) 进行自助排查。
+
+### **应用被杀死后无法弹出来电界面？**
+- 确认收到了推送，收不到推送需要确认下 IM 控制台是否正确上传证书。参见文档上述**厂商配置**的第一步，看下是否添加正确。
+
+- 确认控制台选择了 FCM 数据消息。
+
+- 确认收到数据消息，过滤日志（关键字：TIMPush），检查下述日志是否有打印记录（如果收不到消息，可以使用 IM 控制台的 [排查工具](https://cloud.tencent.com/document/product/269/100629) 查看原因）。
+
+- 确认实现了**自动登录**。自动登录后才会去拉取通话请求，才能显示来电界面。
+
+### 怎样强制使用 FCM 通道？
+
+若您的业务想要强制使用 FCM 通道，可调用以下接口：
+``` java
+TIMPushManager.getInstance().forceUseFCMPushChannel(true);
+```