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

package/resource/knowledge/push/integration/donut.md

@@ -0,0 +1,271 @@
+## 前置条件
+
+### 1. 厂商配置
+
+> **说明：**
+>
+
+> 在 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/intro/) 中开启推送服务，默认支持在线推送。如果您需要使用离线推送，请您先完成厂商配置，具体操作方法可参见 厂商配置 > 微信小程序多端框架。
+>
+
+### 2. 微信开发者工具版本要求
+
+微信开发者工具版本需 ≥ 1.06.2410152，您可进入 [下载地址](https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly.html) 进行版本下载。
+
+## 集成腾讯云消息推送服务
+
+### 步骤1: 推送插件配置
+
+> **说明：**
+>
+
+> 在 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/nightly.html) 中开启推送服务，默认支持在线推送。
+>
+
+【Android】
+
+#### 插件配置
+1. 在可视化界面配置填写插件版本号，勾选开启腾讯云消息推送功能，请查看 [更新日志](https://cloud.tencent.com/document/product/269/114293) 获取插件最新版本号**。**
+
+2. 设置 Android SDK 版本。推送服务所需的微信小程序多端框架 Android SDK 最低版本为 1.4.7，推荐使用 [最新版本](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/changelog/android/changelog.html)。
+
+【iOS】
+
+#### 插件配置
+1. 在可视化界面配置填写插件版本号，勾选开启腾讯云消息推送功能，请查看 [更新日志](https://cloud.tencent.com/document/product/269/114293) 获取插件最新版本号。
+
+2. 设置 iOS SDK 版本。推送服务所需的微信小程序多端框架 iOS SDK 版本号为 `1.4.15` , 推荐使用 [最新的 SDK](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/changelog/ios/changelog.html)。
+
+### 步骤2: 离线推送配置
+
+> **说明：**
+>
+
+> 如果只使用在线推送，则无需进行厂商离线推送配置。
+>
+
+【Android】
+
+#### 离线推送配置
+
+可参见微信小程序多端框架官方文档 [Android 配置原生资源](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/handbook/devtools/android-native-resource.html)。
+1. 配置 timpush-configs.json。
+
+推送服务运行时需要从配置文件读取 appid、appkey 、证书 ID 等信息，需要把相应的 timpush-configs.json 文件放到 assets 文件夹打包到 apk 中，timpush-configs.json 文件可以从 [即时通信 IM 控制台 > 推送服务 Push](https://console.cloud.tencent.com/im/push-plugin-push-identifier) 直接下载：
+
+将 timpush-configs.json 放到原生资源目录的 assets 文件夹下：
+
+2. 配置厂商资源文件。
+
+华为、荣耀、谷歌 FCM 的厂商推送，需要读取各自的配置文件，要把相应的配置文件放在 app 目录下 。
+
+各厂商的配置文件需要分别去厂商的推送控制台下载。
+
+> **注意：**
+>
+
+> 不要修改厂商配置文件名称，否则厂商推送会集成失败。
+>
+
+3. 配置证书指纹（华为、荣耀）。
+
+华为、荣耀需要配置证书指纹才能正常收到离线推送。请参见 [华为证书指纹配置](https://developer.huawei.com/consumer/cn/doc/HMSCore-Guides/android-config-agc-0000001050170137#section1159841225116)、[荣耀证书指纹配置](https://developer.honor.com/cn/docs/11002/guides/android-generate-appsign)。
+4. 配置离线推送消息分类。
+
+厂商推送都有消息分类机制，不同类型也会有不同的推送策略。需正确 [配置推送消息分类](https://cloud.tencent.com/document/product/269/100649) 才能正常收到离线推送。
+
+【iOS】
+
+#### 离线推送配置
+1. 配置证书和描述文件。
+
+请参见 [微信小程序多端框架配置文档](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/handbook/certificate/ios.html) 或 [腾讯云推送厂商配置文档](https://cloud.tencent.com/document/product/269/100624) 以生成 iOS 应用运行时所需的证书和 Provisioning Profile，这些文件将在后续配置中使用。您需要准备以下文件：
+  - **开发证书.p12 **
+
+  - **主 App 描述文件.mobileprovision**
+
+2. Apple Developer 平台 Bundle ID 配置。
+
+请参见 [Apple Developer 平台 Bundle ID 配置指引](https://dev.weixin.qq.com/docs/miniapp/handbook/web/set-bundleid.html)，配置时请勾选以下能力：
+  - **Push Notification**
+
+  - **App Group (按需配置：字段配置可参见 **[生成 App GroupID](https://cloud.tencent.com/document/product/269/100624#ae5590eb-b974-4226-9f1b-720fb0201c85)**)**
+
+  - Donut 建议的权限：Access WiFi Information、Associated Domains、Hotspot、Wireless Accessory Configuration；如果使用苹果登录，还需开启 Sign In with Apple（更多其他权限开发者按需开启，并非越多越好哈）
+
+3. 在 Donut 控制台里绑定移动应用的 Bundle ID。
+
+在 [微信小程序多端应用控制台](https://dev.weixin.qq.com/console/crossPlatform) 里绑定移动应用的 `Bundle ID` ，微信开发者工具在真机运行 iOS 时需要明确 `Bundle ID` 。
+
+4. 苹果推送服务 (APNs) 证书 ID 配置。
+
+**当您需要接入 APNs 时开启厂商通道推送时，**`businessID` 为**必传项**，请先按照 [证书配置文档](https://cloud.tencent.com/document/product/269/100624#22ce926d-49b8-439f-8547-8dad1d135279) 上传证书到推送控制台，之后控制台会为您分配此 ID。
+
+5. 运行前准备。
+
+当您点击 Donut 运行程序运行于真机时，会出现**提示框引导**您使用开发证书（.p12 文件）和主应用程序的描述文件。
+
+> **说明：**
+>
+
+> 接入至此，您已经具备了在线推送和厂商推送的所有推送能力，已可满足绝大部分业务需求。
+>
+
+> 后续 NSE 的配置，推荐您完整测试完推送功能后按照业务需求接入。
+>
+
+6. NSE 功能配置 （可选）
+
+当您希望利用 iOS 10 Service Extension 特性来设置 APNs 离线推送的通知图片或统计消息的到达率时，您需要在相应的 **project.miniapp.json **文件中主动配置 NSE。同时，请确保在证书控制台中**启用 mutable-content** 选项，以便充分利用 iOS 10 Service Extension 的功能。
+
+需要注意的是 NSE 是主 App 的插件，推送能力是主 App 带来的，NSE 是推送服务扩展，因此常用 NSE 来做一些特性需求的。
+
+> **注意：**
+>
+
+> 请再次参见 [微信小程序多端框架配置文档](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/handbook/certificate/ios.html) 或 [腾讯云推送厂商配置文档](https://cloud.tencent.com/document/product/269/100624) 以生成 NSE 的 Provisioning Profile，您需要重复之前生成描述文件的步骤。区别是标识符不同，NSE 的标识符规则如下 ：
+>
+
+> Notification Service Extension (NSE) 的 Bundle ID 通常是主应用程序的 Bundle ID 后面加上扩展的标识符，生成描述文件的步骤和主 App 一致。例如：您的主 App 描述文件（ BundleID 为：`com.yourcompany.yourapp`） 那么您的 NSE 描述文件 （ BundleID 为：`com.yourcompany.yourapp.``extension`）
+>
+
+您需要准备以下文件：
+  - **开发证书.p12  （之前步骤已经准备完毕）**
+
+  - **主 App 描述文件.mobileprovision （之前步骤已经准备完毕）**
+
+  - **Service Extension 的描述文件.mobileprovision（本次功能需要新增的描述文件）**
+
+当您准备好以上文件后，可以按照描述填入相关信息：
+
+> **说明：**
+>
+
+> **NSE 相关配置详细描述如下：**
+>
+> - 开启 NSE：借助 iOS 10 Service Extension 特性统计消息抵达率 及设置 APNs 离线推送的通知图片。
+> - NSE BundleID：通常是主应用程序的 Bundle ID 后面加上扩展的标识符，生成描述文件的步骤和主 App 一致。
+> - NSE profilePath：开发环境下的 NSE 的 Profile 的文件路径，推荐放置于 project.miniapp.json 当前目录。
+> - NSE distributeProfilePath：发布环境下 NSE 的 Profile 的文件路径，推荐放置于 project.miniapp.json 当前目录。
+> - TIMPushAppGroupID，当您需要使用 TIMPush 组件统计推送抵达率时，推荐您按照配置文档配置。
+> - 请您按照情况填写。
+
+## 推送服务使用
+
+### 集成 JS API
+
+> **说明：**
+>
+
+> 如何使用 npm 请查阅[官方文档](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html)，此处不再赘述。
+>
+
+1. 在 miniprogram 目录下执行如下命令安装 @tencentcloud/donut-push：
+
+   ``` bash
+   npm i @tencentcloud/donut-push
+   ```
+2. 在微信开发者工具中构建 npm（**微信开发者工具** > **工具 **> **构建 npm**）
+
+### 使用方法
+
+将 SDKAppID 和 appKey 替换为您在 [IM 控制台 > 推送服务 Push > 概览](https://console.cloud.tencent.com/im/push-plugin-push-identifier) 获取的应用的信息。如图所示：
+
+``` javascript
+import Push from "@tencentcloud/donut-push"
+const sdkAppID = 0; // 您的 SDKAppID
+const appKey = ''; // 客户端密钥
+const registrationID = ""; //用户的 registrationID
+const listener = (param) => {
+  console.log('onEvent', JSON.stringify(param));
+}
+App({
+  onLaunch: function () {
+    // 请确保在调用 registerPush 方法之前设置好registrationID。
+    // 如果您卸载并重新安装应用，registrationID 会发生改变。
+    Push.setRegistrationID(registrationID)
+      .then((res) => {
+          console.info("setRegistrationID", JSON.stringify(res));
+          return Push.registerPush(sdkAppID, appKey);
+      }).then((res) => {
+          console.info("registerPush", JSON.stringify(res));
+          return Push.getRegistrationID();
+      }).then((res) => {
+          console.info("getRegistrationID", JSON.stringify(res));
+      })
+      .catch((res) => {
+          console.error("registerPush failed", JSON.stringify(res));
+    });
+    // 监听在线推送
+    Push.addPushListener(Push.EventName.NOTIFICATION_CLICKED, listener);
+  }
+})
+```
+
+## 体验您的第一次推送
+
+在测试推送前，请务必打开通知和状态栏。进入 [推送服务 Push > 接入测试](https://console.cloud.tencent.com/im/push-plugin-push-check) 发送您的第一条推送。
+
+## 推送结果回调
+
+开启推送服务后，推送结果可以通过配置基础回调的方式，将结果转发给 App 后台，详细可参见：
+- [普通推送结果回调](https://cloud.tencent.com/document/product/269/102567)
+
+- [全员推送结果回调](https://cloud.tencent.com/document/product/269/102568)
+
+## 设备通知栏设置
+
+推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：
+- “**手机设置 **> **通知 **> **锁屏通知 **> **隐藏或者不显示通知**”，会影响锁屏状态下推送通知显示。
+
+- “**手机设置 **> **通知 **> **更多通知设置 **> **状态栏显示通知图标**”，会影响状态栏下推送通知的图标显示。
+
+- “**手机设置 **> **通知 **> **应用的通知管理 **> **允许通知**”，打开关闭会直接影响推送通知显示。
+
+- “**手机设置 **> **通知 **> **应用的通知管理 **> **通知铃声**” 和 “**手机设置 **> **通知 **> **应用的通知管理 **> **静默通知**”，会影响推送通知铃音的效果。
+
+## 厂商推送限制
+1. 国内厂商都有消息分类机制，不同类型也会有不同的推送策略。如果想要推送及时可靠，需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之，推送消息会受厂商推送消息分类影响，与预期会有差异。
+
+2. 另外，一些厂商对于应用每天的推送数量也是有限制的，可以在厂商控制台查看应用每日限制的推送数量。 如果推送消息出现推送不及时或者偶尔收不到情况，需要考虑下这里：
+
+【华为】
+
+将推送消息分为服务与通讯类和资讯营销类，推送效果和策略不同。另外，消息分类还和自分类权益有关：
+- 无自分类权益，推送消息厂商还会进行二次智能分类 。
+
+- 有申请自分类权益，消息分类会按照自定义的分类进行推送。 具体请参见 [厂商描述](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835)。
+
+【vivo】
+
+将推送消息分为系统消息类和运营消息类，推送效果和策略不同。系统消息类型还会进行厂商的智能分类二次修正，若智能分类识别出不是系统消息，会自动修正为运营消息，如果误判可邮件申请反馈。另外，消息推送也受日推总数量限制，日推送量由应用在厂商订阅数统计决定。 具体请参见 [厂商描述1](https://dev.vivo.com.cn/documentCenter/doc/359) 或 [厂商描述2](https://dev.vivo.com.cn/documentCenter/doc/156)。
+
+【OPPO】
+
+将推送消息分为私信消息类和公信消息类，推送效果和策略不同。其中私信消息是针对用户有一定关注度，且希望能及时接收的信息，私信通道权益需要邮件申请。公信通道推送数量有限制。 具体请参见 [厂商描述1](https://open.oppomobile.com/wiki/doc#id=11227) 或 [厂商描述2](https://open.oppomobile.com/wiki/doc#id=11210)。
+
+【小米】
+
+将推送消息分为重要消息类和普通消息类，推送效果和策略不同。其中重要消息类型仅允许即时通讯消息、个人关注动态提醒、个人事项提醒、个人订单状态变化、个人财务提醒、个人状态变化、个人资源变化、个人设备提醒这8类消息推送，可以在厂商控制台申请开通。普通消息类型推送数量有限制。 具体请参见 [厂商描述1](https://dev.mi.com/console/doc/detail) 或 [厂商描述2](https://dev.mi.com/console/doc/detail)。
+
+【魅族】
+
+推送消息数量有限制。 具体请参见 [厂商描述](http://open.res.flyme.cn/fileserver/upload/file/202201/85079f02ac0841da859c1da0ef351970.pdf)。
+
+【FCM】
+
+推送上行消息频率有限制。 具体请参见[厂商描述](https://firebase.google.com/docs/cloud-messaging/throttling-and-quotas)。
+
+## 常见问题
+
+### **为什么在开发者工具上清了缓存但是构建时还是用的原来的基座 App**
+
+需要修改 project.miniapp.json 文件才能重新构建远程基座 App，改一下应用的 version code 再进行构建即可。
+
+### **我可以从哪里查看推送服务 Push 的相关计费信息？**
+
+价格及购买相关问题，请参见 [推送服务计费说明](https://cloud.tencent.com/document/product/269/110762#Push)。
+
+### **iOS 在控制台上测试工具显示“上传 token 无效，请检查”，怎么办？**
+
+需要您检查下上传的 p12证书是否为推送证书、且 Bundle ID 应该是与主 App 一致。

package/resource/knowledge/push/integration/flutter.md

@@ -0,0 +1,363 @@
+## 前提条件
+
+开始接入前，请先完成对应原生平台的推送前提配置：请参见 [iOS 前提条件](https://cloud.tencent.com/document/product/269/100627#.E5.89.8D.E6.8F.90.E6.9D.A1.E4.BB.B6) 和 [Android 前提条件](https://cloud.tencent.com/document/product/269/100626#.E5.89.8D.E6.8F.90.E6.9D.A1.E4.BB.B6)。
+
+## 集成 TIMPush
+
+Flutter 工程需要先引入推送插件，您可以在 `pubspec.yaml` 中添加依赖，也可以执行以下命令自动安装：
+``` bash
+flutter pub add tencent_cloud_chat_push
+```
+
+完成 Flutter 插件集成后，还需要继续完成对应原生平台侧配置。
+
+Android 端请参考 [Android 集成 TIMPush](https://cloud.tencent.com/document/product/269/100626#.E9.9B.86.E6.88.90-timpush) 章节，完成各项配置；其中“集成 TIMPush 依赖”步骤与原生 Android 工程不同，请按下方 Flutter 方式处理。
+
+在 `android/app/build.gradle` 或  `android/app/build.gradle.kts` 按需引入目标厂商的 TIMPush 通道包。只有引入对应厂商包，才能启用该厂商的原生推送能力。`VERSION` 请前往 [更新日志](https://cloud.tencent.com/document/product/269/1606) 获取并替换为实际版本号。
+
+【Groovy DSL】
+``` bash
+dependencies {
+    implementation 'com.tencent.timpush:huawei:VERSION'
+    implementation 'com.tencent.timpush:xiaomi:VERSION'
+    implementation 'com.tencent.timpush:oppo:VERSION'
+    implementation 'com.tencent.timpush:vivo:VERSION'
+    implementation 'com.tencent.timpush:honor:VERSION'
+    implementation 'com.tencent.timpush:meizu:VERSION'
+    implementation 'com.tencent.timpush:fcm:VERSION'
+}
+```
+
+【Kotlin DSL】
+``` bash
+dependencies {
+    implementation("com.tencent.timpush:huawei:VERSION")
+    implementation("com.tencent.timpush:xiaomi:VERSION")
+    implementation("com.tencent.timpush:oppo:VERSION")
+    implementation("com.tencent.timpush:vivo:VERSION")
+    implementation("com.tencent.timpush:honor:VERSION")
+    implementation("com.tencent.timpush:meizu:VERSION")
+    implementation("com.tencent.timpush:fcm:VERSION")
+}
+
+```
+
+Android 端还需要创建或复用自定义 `Application` 类，并继承 `TencentCloudChatPushApplication`。如果工程中已存在自定义 `Application`，直接改为继承该类，并确保 `onCreate`() 中调用 `super.onCreate()`。
+``` java
+package com.example.pushdemo
+
+import com.tencent.chat.flutter.push.tencent_cloud_chat_push.application.TencentCloudChatPushApplication
+
+class MyApplication : TencentCloudChatPushApplication() {
+    override fun onCreate() {
+        super.onCreate()
+    }
+}
+```
+
+然后在 `android/app/src/main/AndroidManifest.xml` 的 `<application>` 标签中配置 `android:name`，指向上述自定义 `Application` 类。
+``` bash
+<application
+    android:name=".MyApplication"
+    ...>
+</application>
+```
+
+iOS 端不需要执行原生 iOS 文档中“主 App target 集成”步骤，Flutter 插件会处理相关依赖。您只需要在 `ios/Runner/AppDelegate.swift` 中补充 TIMPush 相关配置，用于返回推送证书 ID、App Group ID，以及转发离线推送点击事件。
+``` 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)
+    }
+
+    // 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
+    }
+}
+```
+
+## 注册推送
+
+[registerPush](https://cloud.tencent.com/document/product/269/101962#3aab298e-7d51-4b17-ac24-8dd6b2d30e01) 用于注册当前设备的推送 token。注册时机、参数含义和不同接入场景的说明，请参考 [Android 注册推送](https://cloud.tencent.com/document/product/269/100626#.E6.B3.A8.E5.86.8C.E6.8E.A8.E9.80.81) 和 [iOS 注册推送](https://cloud.tencent.com/document/product/269/100627#50e75789-9e42-43b1-b9d1-7cf0dd15b930) 章节。
+
+**请注意，不要在 Flutter 程序入口的 **`main`** 方法中调用。**建议在用户同意隐私政策后，并在业务侧合适时机调用。
+
+【App 冷启动注册 TIMPush（appKey 传 Push Key）】
+``` javascript
+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}',
+  );
+}
+```
+
+【IM 登录后注册推送（appKey 传 null）】
+``` javascript
+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}',
+  );
+}
+```
+
+## 配置消息触达统计（可选）
+
+触达统计主要涉及厂商控制台、回执地址、APNs Notification Service Extension、App Group 等平台专属配置，请参考 [Android 配置消息触达统计](https://cloud.tencent.com/document/product/269/100626#.E9.85.8D.E7.BD.AE.E6.B6.88.E6.81.AF.E8.A7.A6.E8.BE.BE.E7.BB.9F.E8.AE.A1.EF.BC.88.E5.8F.AF.E9.80.89.EF.BC.89) 和 [iOS 配置消息触达统计](https://cloud.tencent.com/document/product/269/100627#.E9.85.8D.E7.BD.AE.E6.B6.88.E6.81.AF.E8.A7.A6.E8.BE.BE.E7.BB.9F.E8.AE.A1.EF.BC.88.E5.8F.AF.E9.80.89.EF.BC.89) 文档。
+
+iOS 如需统计推送触达数据，请在 `registerPush` 时传入 `applicationGroupID`，并确认 `ios/Runner/AppDelegate.swift` 中已实现 `applicationGroupID()`。
+
+## 测试推送
+
+运行 App 后，过滤 `TIMPush` 关键字查看注册日志。注册成功后，调用 `getRegistrationID()` 获取当前设备推送标识。控制台或服务端发送测试消息时，可使用该值定位设备。
+
+测试流程请参考 [Android 测试推送](https://cloud.tencent.com/document/product/269/100626#.E6.B5.8B.E8.AF.95.E6.8E.A8.E9.80.81) 和 [iOS 测试推送](https://cloud.tencent.com/document/product/269/100627#.E6.B5.8B.E8.AF.95.E6.8E.A8.E9.80.81)文档。仅集成 TIMPush 的用户，建议优先使用腾讯云控制台接入测试能力验证离线推送。
+
+如果您的项目已接入 IM SDK，可通过 SDK API 发送一条带离线推送参数的消息进行验证。Flutter 侧示例如下：
+``` java
+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}',
+  );
+}
+```
+
+## 处理通知点击跳转
+
+通知点击跳转完整流程请参考 [Android 处理通知点击跳转](https://cloud.tencent.com/document/product/269/100626#.E5.A4.84.E7.90.86.E9.80.9A.E7.9F.A5.E7.82.B9.E5.87.BB.E8.B7.B3.E8.BD.AC) 和 [iOS 处理通知点击跳转](https://cloud.tencent.com/document/product/269/100627#.E5.A4.84.E7.90.86.E9.80.9A.E7.9F.A5.E7.82.B9.E5.87.BB.E8.B7.B3.E8.BD.AC) 文档。Flutter 侧主要关注两处差异：通过 IM SDK API 发送消息时写入 `ext`，以及在客户端注册监听并解析 `ext`。
+
+如果您的项目已接入 IM SDK，可在发送消息时通过 `OfflinePushInfo.ext` 携带跳转参数。示例代码如下：
+``` java
+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}',
+  );
+}
+```
+
+Flutter 客户端推荐使用 `TencentCloudChatPush().addPushListener` 监听通知点击事件，并在 `onNotificationClicked` 中解析 `ext`。示例代码如下：
+``` java
+
+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}`。
+> - 若 App 冷启动后需要立即处理点击事件，建议尽早注册 `listener`，例如在登录流程完成后、业务首页初始化前完成注册。
+
+## 配置消息分类（可选）
+
+消息分类属于 Android 厂商通道策略，Flutter 侧没有额外的接入操作，请参考 [Android 配置消息分类](https://cloud.tencent.com/document/product/269/100626#config_category) 文档，API 请参考 [Flutter 消息分类 API](https://pub.dev/documentation/tencent_cloud_chat_sdk/latest/enum_offlinePushInfo/OfflinePushInfo-class.html) 文档。
+
+## 收不到推送排障流程
+
+### 步骤一 原生侧排查
+
+如果发送测试消息后设备没有收到推送，请先按平台文档 [Android 收不到推送排障流程](https://cloud.tencent.com/document/product/269/100626#.E6.94.B6.E4.B8.8D.E5.88.B0.E6.8E.A8.E9.80.81.E6.8E.92.E9.9A.9C.E6.B5.81.E7.A8.8B) 和 [iOS 收不到推送排障流程](https://cloud.tencent.com/document/product/269/100627#.E6.94.B6.E4.B8.8D.E5.88.B0.E6.8E.A8.E9.80.81.E6.8E.92.E9.9A.9C.E6.B5.81.E7.A8.8B) 完成原生侧排查。
+
+### 步骤二 Flutter 侧可按以下顺序补充检查
+1. 确认 `registerPush` 返回 `code = 0`。如果返回非 0，请先根据错误码和 `errorMessage` 排查，不要只看 App 是否启动成功。
+
+2. 注册成功后调用 `getRegistrationID()`，确认返回值非空。控制台或服务端发送测试消息时，使用的 `RegistrationID / userID` 应与这里返回的值一致。
+
+3. 确认 `registerPush` 的调用时机正确。仅使用 Push 能力时，可在 App 完成必要初始化、用户同意隐私政策并获得通知权限后调用；Chat / TUIKit 离线推送场景下，应在 IM 登录成功后调用。
+
+4. 确认通知点击逻辑已通过 `TencentCloudChatPush().addPushListener` 注册。`registerPush` 中的 `onNotificationClicked` 参数当前仅作为必填空实现保留，不建议继续在其中处理跳转。
+
+5. 如果通过 Chat SDK 发送测试消息，确认 `OfflinePushInfo` 中已设置 `title`、`desc`，并按业务需要设置 `ext`。如需点击跳转，`ext` 中应包含客户端可解析的页面或会话参数。
+
+### 仍无法解决