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

package/resource/knowledge/push/integration/uni-app.md

@@ -0,0 +1,461 @@
+## 前提条件
+
+开始接入前，请先完成对应原生平台的推送前提配置：iOS 和 Android 端请分别参见 [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)，HarmonyOS 端请参见 鸿蒙厂商配置。
+
+> **版本兼容：**
+>
+> - HBuilderX（[官网下载](https://www.dcloud.io/hbuilderx.html)）：推荐 4.36 ~ 4.63 或 4.66 及以上版本，4.64、4.65 存在 bug 请避开。
+> - [TencentCloud-Push 插件](https://ext.dcloud.net.cn/plugin)：使用 1.1.0 及以上版本；Harmony 推送需 1.3.0 及以上版本。
+> - uni-app x 项目：HBuilderX 需 4.55 及以上版本。
+
+本文示例中的 `SDKAppID`、`AppKey`、`businessID`、厂商 AppID、厂商 AppKey 均为占位符，请替换为实际值，切勿在代码仓库中提交真实密钥。
+
+## 集成 TencentCloud-Push
+
+请按下述步骤依次完成下载插件并导入 HBuilderX、配置离线推送文件。
+
+### 下载插件并导入 HBuilderX
+1. 完成上述「前提条件」中目标平台的厂商配置后，打开 [uni-app 腾讯云推送服务（Push）](https://ext.dcloud.net.cn/plugin)，单击**下载插件并导入 HBuilderX**，将插件导入 HBuilderX 工程中。
+
+2. 选择需要集成的工程并单击**确定**。
+
+3. 集成后效果如下图所示：
+
+### 配置离线推送文件
+
+> **说明：**
+>
+> - 推送配置文件统一放在与 `uni_modules` 平级的 `nativeResources` 目录下，若该目录不存在请手动新建。
+> - 建议将 HBuilderX 与 TencentCloud-Push 插件升级到最新版本，以规避旧版本（如 HBuilderX 4.36 之前）在 vivo/荣耀 等厂商通道上的兼容性问题。
+
+请根据目标平台展开下方对应页签，按步骤放置配置文件：
+
+【Android】
+1. 新建 `nativeResources/android/assets` 目录。
+
+2. 配置 `timpush-configs.json`（在 [推送服务 Push > 推送设置 > 厂商配置](https://console.cloud.tencent.com/im/push-plugin-push-setting) 下载），到 `nativeResources/android/assets/` 目录下。如图所示：
+
+3. 按目标厂商配置华为、荣耀、vivo、FCM。
+
+【FCM】
+1. 配置 `com.google.gms.google-services` 到 `uni_modules/TencentCloud-Push/utssdk/app-android/config.json` 的 `project.plugins` 中，如下所示：
+
+``` json
+"project": {
+  	"plugins": [
+        ...
+  		"com.google.gms.google-services"
+  	],
+  	"dependencies": [
+  		"com.huawei.agconnect:agcp:1.9.1.301",
+		"com.google.gms:google-services:4.3.15",
+		"com.hihonor.mcs:asplugin:2.0.1.300"
+  	]
+}
+```
+
+2. 配置 `google-services.json` 文件到 `nativeResources/android/`目录下（注意！请勿配置到 `nativeResources/android/assets` 目录下）。如图所示：
+
+【华为】
+
+【荣耀】
+1. 编辑 `uni_modules/TencentCloud-Push/utssdk/app-android/config.json` 的 `dependencies`，添加 `"com.tencent.timpush:honor:xxxx"`。如图所示：
+
+``` bash
+{
+     ...
+     "dependencies": [
+         ...
+         "com.tencent.timpush:honor:8.5.6864"
+     ]
+}
+```
+
+2. 配置 `mcs-services.json` 文件到 `nativeResources/android`（在荣耀开发者服务平台下载，详见 荣耀厂商配置）目录下。如图所示：
+
+3. 配置 `appID` 到 `nativeResources/android/manifestPlaceholders.json` 中的 `"HONOR_APPID"`。
+
+``` bash
+{
+     "HONOR_APPID": ""
+}
+```
+
+【vivo】
+1. 编辑 `uni_modules/TencentCloud-Push/utssdk/app-android/config.json` 的 `dependencies`，添加 `"com.tencent.timpush:vivo:xxxx"`。如图所示：
+
+``` bash
+{
+     ...
+     "dependencies": [
+         ...
+         "com.tencent.timpush:vivo:8.5.6864"
+     ]
+}
+```
+
+2. 配置 `AppID` 和 `AppKey` 到 `nativeResources/android/manifestPlaceholders.json` 中的 `VIVO_APPKEY` 和 `VIVO_APPID`。
+
+``` bash
+{
+     "VIVO_APPKEY": "",
+     "VIVO_APPID": "",
+}
+```
+
+【iOS】
+1. 新建 `nativeResources/ios/Resources` 目录；
+
+2. 在 `nativeResources/ios/Resources` 中新建 `timpush-configs.json` 文件；
+
+3. 并将在 [IM 控制台 > 推送服务 Push > 推送设置](https://console.cloud.tencent.com/im/push-plugin-push-identifier) 获取的证书 ID，补充到 `timpush-configs.json` 文件中。如下所示：
+
+``` json
+{
+    "businessID":"xxx"
+}
+```
+
+【Harmony】
+1. 在 [IM 控制台 > 推送服务 Push > 推送设置](https://console.cloud.tencent.com/im/push-plugin-push-identifier) 获取的证书 ID。
+
+2. 将证书 ID 补充到 `uni_modules/TencentCloud-Push/utssdk/app-harmony/resources/rawfile/timpush-configs.json` 文件中。如下所示：
+
+``` json
+{
+    "businessID":"xxx"
+}
+```
+
+## 注册推送
+
+完成插件导入和离线推送文件配置后，在 App 启动、用户同意隐私政策后调用 `registerPush` 注册推送服务，并按需注册通知点击、在线推送等监听。
+
+注册推送涉及 `registrationID` 和 `userID` 两个推送标识，理解它们的区别有助于后台正确下发离线推送：
+
+|**推送标识**|**说明**|**获取 / 设置方式**|
+|---------|---------|---------|
+|`registrationID`|推送服务为每台设备分配的唯一推送标识。`registerPush` 成功后，后台即可凭 `registrationID` 向该设备下发离线推送。|注册成功后通过 `getRegistrationID` 获取。|
+|`userID`|与 Chat 登录打通的业务用户标识。希望后台直接向 Chat 登录 `userID` 推送（即接收 Chat 离线消息）时使用。|在 `registerPush` 前调用 `setRegistrationID(userID)` 绑定，绑定后 `registrationID` 即等于该 `userID`。|
+
+> **注意：**
+>
+> - 仅使用 TIMPush（独立推送）：直接调用 `registerPush`，后台使用 `getRegistrationID` 返回的 `registrationID` 推送即可。
+> - 与 Chat 打通：在 `registerPush` 前调用 `setRegistrationID(userID)`，且 `userID` 必须与 Chat 登录使用的 `userID` 完全一致，否则会产生账号互踢导致推送丢失。
+
+### 引入并注册推送服务
+
+将 `SDKAppID` 和 `appKey` 替换为您在 [IM 控制台 > 推送服务 Push > 概览](https://console.cloud.tencent.com/im/push-plugin-push-identifier) 获取的应用信息。如图所示：
+
+``` javascript
+// 集成 TencentCloud-Push
+import { setRegistrationID, registerPush, getRegistrationID, EVENT, addPushListener } from '@/uni_modules/TencentCloud-Push';
+const SDKAppID = 0; // 您的 SDKAppID
+const appKey = ''; // 客户端密钥
+
+// 如果您需要与 Chat 的登录 userID 打通（即向此 userID 推送消息），请使用 setRegistrationID 接口
+// setRegistrationID(userID, () => {
+    // console.log('setRegistrationID ok', userID);
+// });
+
+registerPush(SDKAppID, appKey, (data) => {
+        console.log('registerPush ok', data);
+        getRegistrationID((registrationID) => {
+            console.log('getRegistrationID ok', registrationID);
+        });
+    }, (errCode, errMsg) => {
+        console.error('registerPush failed', errCode, errMsg);
+    }
+);
+
+// 监听通知栏点击事件，获取推送扩展信息
+addPushListener(EVENT.NOTIFICATION_CLICKED, (res) => {
+    // res 为推送扩展信息
+    console.log('notification clicked', res);
+});
+
+// 监听在线推送
+addPushListener(EVENT.MESSAGE_RECEIVED, (res) => {
+    // res 为消息内容
+    console.log('message received', res);
+});
+
+// 监听在线推送被撤回
+addPushListener(EVENT.MESSAGE_REVOKED, (res) => {
+    // res 为被撤回的消息 ID
+    console.log('message revoked', res);
+});
+```
+
+**验证**：`registerPush` 成功回调被触发；登录 [IM 控制台 > 推送服务 Push 排查工具](https://cloud.tencent.com/document/product/269/100629)，输入 `userID` 或 `registrationID`，确认 token 已上传。如触发失败回调，可按 错误码 查询 `errCode` 含义。
+
+### 自定义 registrationID（可选）
+
+如需自定义推送标识（如使用业务侧用户 ID），可在 `registerPush` 前调用 `setRegistrationID`。
+``` javascript
+import { setRegistrationID, registerPush } from '@/uni_modules/TencentCloud-Push';
+
+// 在 registerPush 前调用，userID 建议与 Chat 登录使用的 userID 一致
+setRegistrationID(userID, () => {
+    console.log('setRegistrationID ok', userID);
+    registerPush(SDKAppID, appKey, (data) => {
+        console.log('registerPush ok', data);
+    }, (errCode, errMsg) => {
+        console.error('registerPush failed', errCode, errMsg);
+    });
+});
+```
+
+> **注意：**
+>
+
+> 混用场景下，自定义 `registrationID` 必须与 IM 登录使用的 `userID` 完全一致，否则会产生账号互踢导致推送丢失。
+>
+
+## 生成自定义调试基座（Android、iOS）
+
+> **说明：**
+>
+
+> Harmony 不需要自定义基座。
+>
+
+单击 HBuilderX 的**运行** > **运行到手机或模拟器** > **制作自定义调试基座**，使用云端证书制作 Android 或 iOS 自定义调试基座。
+
+**验证**：自定义基座制作成功，可在目标厂商真机上正常安装并运行 App，无崩溃。如启动崩溃，请检查 `config.json` 依赖/插件配置、厂商配置文件位置是否正确。
+
+## 测试推送
+
+完成上述集成步骤后，需要通过发送测试消息验证链路是否打通。发送消息前请确认：
+1. Android 13 及以上已允许通知权限；
+
+2. Android 8.0 及以上目标通知渠道已开启（包括横幅、锁屏、声音开关）；
+
+3. App 已运行在自定义基座上，并已置于后台。
+
+   在测试推送前，请务必打开通知和状态栏。进入 [推送服务 Push > 接入测试](https://console.cloud.tencent.com/im/push-plugin-push-check) 发送您的第一条推送。
+
+   **验证**：App 置于后台后发送测试消息，设备能收到离线推送通知。如果收不到，请参见下文「收不到推送排障流程」逐步排查。
+
+## 处理通知点击跳转
+
+通知点击跳转需要三步配合完成：控制台配置点击动作、发送推送时携带跳转参数、客户端注册监听并解析参数。三步缺一则跳转不生效。
+
+### 配置控制台点击动作
+
+在 IM 控制台配置推送证书的「点击后续动作」，勾选「打开应用内指定界面」：
+
+操作路径：IM 控制台 > **推送服务 Push** > **推送设置** > **对应厂商证书** > **编辑** > 点击后续动作，选择**打开应用内指定界面**，并保持默认填充值不修改。
+
+### 发送推送时携带 ext
+
+发送离线推送时，通过 `ext` 字段携带跳转所需的业务信息（如目标页面、会话 ID 等）。`ext` 是一个字符串，结构由业务自定义，推荐使用 JSON 格式便于客户端解析。下文示例统一使用如下结构演示：
+``` json
+# conversationType 为 1 表示单聊（conversationID 填消息发送方 userID），为 2 表示群聊（conversationID 填 groupID）。
+{"conversationID":"user_A","conversationType":1}
+```
+
+【控制台发送】
+
+进入 [推送服务 Push > 接入测试](https://console.cloud.tencent.com/im/push-plugin-push-check) 发送推送时，在 `Ext` 字段中填入 JSON 字符串即可。
+
+【REST API 发送】
+
+如果需要通过服务端发送推送，可参考 [REST API 接口 - 发起全员/标签推送](https://cloud.tencent.com/document/product/269/100634)，在请求体的 `OfflinePushInfo.Ext` 字段中设置 JSON 字符串：
+``` json
+{
+    "MsgBody": [],
+    "OfflinePushInfo": {
+        "PushFlag": 0,
+        "Title": "离线推送标题",
+        "Desc": "离线推送内容",
+        "Ext": "{\"conversationID\":\"user_A\",\"conversationType\":1}"
+    }
+}
+```
+
+### 客户端注册监听并解析 ext
+
+在 App 启动时调用 `addPushListener` 注册 `EVENT.NOTIFICATION_CLICKED` 事件，回调中的 `res` 为发送端通过 `ext` 携带的推送扩展信息。解析后即可跳转到业务页面。以下示例只演示解析核心逻辑，跳转部分用 `TODO` 占位，请按自身业务补充：
+``` javascript
+import { addPushListener, EVENT } from '@/uni_modules/TencentCloud-Push';
+
+addPushListener(EVENT.NOTIFICATION_CLICKED, (res) => {
+    console.log('notification clicked', res);
+
+    if (!res) {
+        return;
+    }
+
+    // 1. 解析 ext。res 为发送端通过 ext 携带的推送扩展信息，结构由业务自定义。
+    let data = res;
+    if (typeof res === 'string') {
+        try {
+            data = JSON.parse(res);
+        } catch (e) {
+            console.error('parse ext failed', e);
+            return;
+        }
+    }
+
+    const conversationID = data.conversationID;
+    const conversationType = data.conversationType;
+
+    // 2. TODO: 根据业务字段跳转到目标页面。
+    //    若使用了 Chat / TUIKit，建议在用户登录成功后再跳转；
+    //    冷启动场景可先把参数缓存起来，登录回调中再跳转。
+});
+```
+
+**验证**：点击通知后 `EVENT.NOTIFICATION_CLICKED` 回调被调用，且 `res` 内容与发送时设置的 `ext` 一致。如果回调未触发，请检查：控制台点击动作是否选择了「打开应用内指定界面」并保持默认填充值、监听器是否在 App 启动时注册、发送消息时是否设置了 `ext`。
+
+## 推送结果回调
+
+开启推送服务后，推送结果可以通过配置基础回调的方式，将结果转发给 App 后台，详见：
+- [普通推送结果回调](https://cloud.tencent.com/document/product/269/102567)
+
+- [全员推送结果回调](https://cloud.tencent.com/document/product/269/102568)
+
+## 设备通知栏设置
+
+推送的直观表现就是通知栏提示，所以同其他通知一样受设备通知相关设置的影响，以华为为例：
+- “手机设置 > 通知 > 锁屏通知 > 隐藏或者不显示通知”，会影响锁屏状态下推送通知显示。
+
+- “手机设置 > 通知 > 更多通知设置 > 状态栏显示通知图标”，会影响状态栏下推送通知的图标显示。
+
+- “手机设置 > 通知 > 应用的通知管理 > 允许通知”，打开关闭会直接影响推送通知显示。
+
+- “手机设置 > 通知 > 应用的通知管理 > 通知铃声” 和 “手机设置 > 通知 > 应用的通知管理 > 静默通知”，会影响推送通知铃声的效果。
+
+## 配置消息分类（可选）
+
+厂商离线通道通常有消息分类机制。消息分类会影响推送及时性、单设备每日接收数量、夜间展示、声音、横幅以及厂商通道权限。
+
+> **注意：**
+>
+
+> 只有 IM 聊天、订单、交易、账号变更等用户预期强、需要及时触达的消息，才建议申请或使用高优先级分类。营销、广告、活动、资讯类消息不应滥用高优分类，否则可能被厂商降级、限频或冻结权限。
+>
+
+离线推送由发送端（服务端 REST API 或 Chat SDK）在发送消息时携带分类参数，TencentCloud-Push 插件本身不负责发送。发送离线推送时，可通过离线推送参数（REST API 的 `OfflinePushInfo` 或 Chat SDK 的 `V2TIMOfflinePushInfo`）设置各厂商消息分类，API 设置优先级通常高于腾讯云控制台证书的默认配置。不同厂商的分类机制如下：
+
+|**厂商**|**分类机制**|
+|---------|---------|
+|小米|按渠道 `channelID` 区分重要消息类与普通消息类。|
+|华为|按 `category` 区分服务与通讯类、资讯营销类。|
+|OPPO|按 `category` 区分私信类与公信类，并可设置通知提醒等级。|
+|vivo|按 `category` 区分系统消息类与运营消息类。|
+|荣耀|按 `importance` 区分，`NORMAL` 表示服务通讯类，`LOW` 表示资讯营销类。|
+|魅族|区分公信消息与私信消息。|
+|FCM|通过通道 `channelID` 设置 Android 8.0 及以上通知渠道。|
+
+## 厂商推送限制
+
+> **注意：**
+>
+
+> 只有 IM 聊天、订单、交易、账号变更等用户预期强、需要及时触达的消息，才建议申请或使用高优先级分类。营销、广告、活动、资讯类消息不应滥用高优分类，否则可能被厂商降级、限频或冻结权限。
+>
+
+- 国内厂商都有消息分类机制，不同类型也会有不同的推送策略。如果想要推送及时可靠，需要按照厂商规则设置自己应用的推送类型为高优先级的系统消息类型或者重要消息类型。反之，推送消息会受厂商推送消息分类影响，与预期会有差异。
+
+- 另外，一些厂商对于应用每天的推送数量也是有限制的，可以在厂商控制台查看应用每日限制的推送数量。如果推送消息出现推送不及时或者偶尔收不到情况，需要考虑下这里：
+
+【华为】
+
+将推送消息分为服务与通讯类和资讯营销类，推送效果和策略不同。另外，消息分类还和自分类权益有关：
+- 无自分类权益，推送消息厂商还会进行二次智能分类。
+
+- 有申请自分类权益，消息分类会按照自定义的分类进行推送。具体请参见 [厂商描述](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/scale-fcm)。
+
+## 收不到推送排障流程
+
+如果发送测试消息后设备没有收到推送，请按以下流程逐步排查。每一步确认通过后再进入下一步，可以快速定位问题所在环节。
+
+#### 步骤1：确认 registerPush 是否成功
+
+检查 `registerPush` 回调结果：
+- **成功回调触发**：注册成功，进入第二步。
+
+- **失败回调触发**：注册失败。查看 `errCode`、`errMsg`：
+
+- TIMPush 错误码（如 `800006`）：在 错误码 中查询。
+
+- 厂商原始异常（如 `6003: certificate fingerprint error`）：优先根据此信息排查厂商侧配置。
+
+- 常见原因：`timpush-configs.json` 缺失或位置错误、厂商证书未添加、包名或 SHA256 指纹不匹配、厂商配置文件未放置、未使用云端证书制作自定义基座。
+
+#### 步骤2：确认控制台能查到设备
+
+在控制台 [排查工具](https://cloud.tencent.com/document/product/269/100629) 中输入 `registrationID` 或 `userID`：
+- **能查到设备且状态正常**：进入第三步。
+
+- **查不到设备**：`registerPush` 可能实际未成功，或使用了错误的标识。重新确认 `registrationID` / `userID` 值是否正确。
+
+#### 步骤3：确认 App 状态
+
+离线推送只在 App 处于后台或已杀进程时触发：
+- **App 在前台**：将 App 切到后台或杀掉进程，重新发送测试消息。
+
+- **App 已在后台**：进入第四步。
+
+#### 步骤4：确认通知权限和通知渠道
+- **Android 13 及以上**：确认 App 已获得通知权限（系统设置 > 应用 > 通知 > 允许通知）。
+
+- **Android 8.0 及以上**：确认目标通知渠道的横幅、锁屏、声音开关已打开（系统设置 > 应用 > 通知 > 通知类别）。
+
+- 通知总开关打开不代表所有 channel 都已开启；需要进入具体通知类别检查。
+
+#### 步骤5：确认基座与打包配置
+- 是否使用云端证书制作了自定义基座，并在自定义基座上运行（标准基座不包含厂商推送通道）。
+
+- `config.json` 中的 `dependencies` / `plugins` 是否按目标厂商正确配置。
+
+#### 步骤6：确认厂商通道配置
+- 测试真机厂商是否与目标厂商通道一致（如不要在华为设备上测试荣耀配置）。
+
+- 厂商平台应用包名是否与 uni-app 工程包名完全一致。
+
+- 厂商证书是否已在 IM 控制台添加且未过期。
+
+- 华为/荣耀：测试包签名的 SHA-256 必须已在厂商控制台「项目设置 > 常规 > SHA 证书指纹」中添加，指纹不一致会报 `6003: certificate fingerprint error`。
+
+#### 步骤7：确认消息分类和厂商限制
+- 是否超出厂商单日推送限额（如 vivo 运营消息每日限制、小米普通消息限额）。
+
+- 是否在夜间发送（部分厂商运营消息夜间不下发）。
+
+- 是否未申请消息分类导致走默认策略被限频。
+
+- 推送服务是否到期（试用到期后自动停止服务）。
+
+#### 步骤8：确认通知展示问题
+
+如果收到了推送（有声音或状态栏图标）但没有横幅或锁屏展示：
+- 检查系统通知类别中的「横幅通知」和「锁屏通知」开关。
+
+- 确认通知渠道不是“静默通知”模式。
+
+- 部分厂商定制系统可能额外限制通知展示方式。
+
+#### 仍无法解决