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

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

@@ -1,357 +0,0 @@
-
-本文档将指导您如何基于 `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);
-```