@tencentcloud/sdk-mcp 1.4.1 → 1.4.3-beta.1

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

@@ -0,0 +1,357 @@
+
+本文档将指导您如何基于 `tencent_cloud_chat_push` 插件实现离线推送功能，适用于使用 AtomicX Core 进行无 UI 集成的场景。
+
+### 效果展示
+
+| Android（FCM） | iOS（APNs） |
+| --- | --- |
+|  |  |
+
+## 开通服务
+
+进入 IM 控制台的插件市场，单击立即购买或免费试用（每个应用可免费试用一次，有效期 7 天）。
+
+> **注意：**
+> 推送插件试用或购买到期后，将自动停止提供推送服务（包括普通消息离线推送、全员/标签推送等服务）。为避免影响您业务的正常使用，请提前购买/续费。
+
+## 集成建议 \[必看\]
+
+### 如何选择推送渠道？
+
+由于 FCM 依赖于 Google 服务，请根据您的业务运营区域选择合适的集成策略：
+
+**跨国全球业务（涉及国内外）：**为确保全球范围内消息的触达率，建议同时集成国内各厂商推送服务以及 FCM 推送服务。
+
+**仅限海外市场（不涉及中国大陆）：**无需集成国内厂商服务。请直接参考本文档集成 FCM Data Message 即可。
+
+**仅限中国大陆境内：**无需集成 FCM。请参考集成 Notification，按需集成 Notification（小米、华为、OPPO、vivo 等国内厂商）推送即可。
+
+### 如何提高推送触达率？
+
+根据我们的经验，超过 90% 的用户接不到通话通知的原因是手动关闭了应用的通知权限。为确保通话可达率，我们强烈建议：
+
+1. **审慎发送通知：**避免向用户推送低质量或无关联的通知，减少用户因骚扰而关闭通知权限的可能性。
+
+2. **提供精细控制：**借鉴微信等优秀应用的做法，在应用设置内为用户提供独立的开关，分别控制 Notification 和 FCM Data Message，而非引导用户去系统设置中一刀切地关闭所有通知。
+
+## 通用配置
+
+**安装组件**：在工程的根目录下，通过命令行执行以下命令安装 `tencent_cloud_chat_push` 插件。
+
+```bash
+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` 文件中添加如下依赖：
+
+**build.gradle.kts：**
+
+```kotlin
+implementation("com.tencent.timpush:fcm:8.8.7375")
+```
+
+**build.gradle：**
+
+```groovy
+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 类，则可直接复用，不需要再次创建。
+
+```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` 下添加以下配置：
+
+```groovy
+buildscript {
+    dependencies {
+        classpath 'com.google.gms:google-services:4.3.15'
+    }
+}
+```
+
+在项目的 app 目录下的 `build.gradle` 文件中添加下方配置：
+
+```groovy
+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）页面。
+2. 单击 Identifiers 右侧的 **+**。您可以新建一个 AppID，或者在您原有的 AppID 上增加 Push Notification Service。
+
+> **说明：**
+> 您 App 的 Bundle ID 不能使用通配符 `*`，否则将无法使用远程推送服务。
+
+配置步骤：勾选 App IDs，单击 Continue；选择 App，单击 Continue；配置 Bundle ID 等其他信息并 Continue；勾选 Push Notifications，开启远程推送服务。
+
+#### 生成证书
+
+1. 选中您的 AppID，选择 Configure。在 Apple Push Notification service SSL Certificates 窗口中有两个 SSL Certificate，分别用于开发环境（Development）和生产环境（Production）。
+2. 先选择开发环境（Development）的 Create Certificate；按提示在 Mac 钥匙串访问中生成 Certificate Signing Request（CSR）并上传。
+3. 生成后下载开发环境的 Development SSL Certificate；再按相同流程生成并下载生产环境的 Production SSL Certificate。
+
+> **说明：**
+> 生产环境的证书实际是开发（Sandbox）+ 生产（Production）的合并证书，可以同时作为开发环境和生产环境的证书使用。
+
+4. 双击打开下载的 SSL Certificate 导入钥匙串；在登录 > 我的证书中，右键分别导出开发与生产环境的 `.p12` 文件。**保存 p12 时请务必设置密码**。
+
+#### 上传证书到控制台
+
+1. 登录即时通信 IM 控制台。
+2. 单击目标应用卡片，进入应用的基础配置页面。
+3. 单击 iOS 原生离线推送设置右侧的添加证书。
+4. 选择证书类型，上传 iOS 证书（.p12），设置证书密码，单击确认。
+
+> **注意：**
+> 上传证书名最好使用全英文（尤其不能使用括号等特殊字符）。上传证书需要设置密码，无密码收不到推送。发布 App Store 的证书需要设置为生产环境，否则无法收到推送。上传的 p12 证书必须是自己申请的真实有效的证书。
+
+5. 待推送证书信息生成后，记录证书的 ID。
+
+### 步骤2：推送参数配置
+
+请将您在厂商配置步骤中获取到的 iOS APNs 推送证书上传至 IM 控制台。IM 控制台会为您分配证书 ID。
+
+注册推送需要将此证书 ID（`apnsCertificateID`）传入：
+
+```dart
+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 推送厂商配置）。此二项若已在前序步骤指定且无修改必要，可不再传入。
+
+```dart
+TencentCloudChatPush().registerPush(
+    onNotificationClicked: _onNotificationClicked,
+    sdkAppId: 您的sdkAppId,
+    appKey: "客户端密钥",
+    apnsCertificateID: 您配置的证书 ID);
+```
+
+2. **实现 Android 自动登录。** FCM 的 data 模式只能将离线 App 唤醒，所以还需要您在 `onAppWakeUpEvent` 中实现登录以及拉起 App 等操作。
+
+```dart
+TencentCloudChatPush().registerOnAppWakeUpEvent(onAppWakeUpEvent: () {
+      // TODO: 登录操作
+});
+```
+
+### 步骤2：自定义来电通知样式（FCM）
+
+您可以使用第三方插件（如 `flutter_local_notifications`）弹出通知，或在原生层创建 `NotificationView` 实现更高级样式。以下为 `flutter_local_notifications` 示例。
+
+**集成插件**
+
+```bash
+flutter pub add flutter_local_notifications
+```
+
+**弹出通知**
+
+```dart
+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** 会自动补发。您可以：
+
+1. **监听来电事件：**订阅 `onCallReceived`，该事件在收到来电时触发，并包含通话所需关键信息。
+2. **展示来电通知：**在该回调中根据事件携带信息调用自定义通知（参考步骤 2）。
+
+```dart
+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();
+    }
+  });
+}
+```
+
+## 常见问题
+
+若在集成过程中遇到问题，请务必先查阅插件推送的常见问题进行自助排查。
+
+### 应用被杀死后无法弹出来电界面？
+
+1. 确认收到了推送，收不到推送需要确认 IM 控制台是否正确上传证书。参见文档厂商配置的第一步，看下是否添加正确。
+2. 确认控制台选择了 FCM 数据消息。
+3. 确认收到数据消息；过滤日志（关键字：TIMPush）检查是否有相关打印（如果收不到消息，可以使用 IM 控制台的排查工具查看原因）。
+4. 确认实现了自动登录。自动登录后才会去拉取通话请求，才能显示来电界面。
+
+### 怎样强制使用 FCM 通道？
+
+若您的业务想要强制使用 FCM 通道，可调用：
+
+```java
+TIMPushManager.getInstance().forceUseFCMPushChannel(true);
+```