@tencentcloud/sdk-mcp 1.6.4 → 1.6.5

package/resource/knowledge/push/api-reference/harmonyos.md

@@ -0,0 +1,140 @@
+## TIMPushManager 接口概览
+
+|API|描述|
+|---------|---------|
+|registerPush|注册推送服务， (必须在 App 用户同意了隐私政策后，再调用该接口使用推送服务)。|
+|unRegisterPush|反注册关闭推送服务。|
+|setRegistrationID|RegistrationID 是推送接收设备的唯一标识 ID。默认情况下，注册推送服务成功时自动生成该 ID，同时也支持您自定义设置。您可根据 RegistrationID 向指定设备推送消息。需要注意的是，卸载并重新安装设备会更改 RegistrationID，因此需要在注册推送服务之前调用 setRegistrationID 接口。|
+|getRegistrationID|在成功注册推送服务后，调用此接口可获取推送接收设备的唯一标识 ID，即 RegistrationID。|
+|addPushListener|添加 Push 监听器。|
+|removePushListener|移除 Push 监听器。|
+|disablePostNotificationInForeground|应用在前台时，开/关通知栏通知（默认开）。|
+
+## 接口详情
+
+### 注册推送服务
+
+#### 接口
+``` tsx
+registerPush(
+  context: Context,
+  sdkAppId?: number,
+  appKey?: string,
+  businessId?: number
+): Promise<TIMPushResult>;
+```
+
+#### 参数说明：
+| 参数 | 类型 | 说明 | 获取路径 |
+| --- | --- | --- | --- |
+| context | Context | 应用上下文 | - |
+| sdkAppId | number | 推送服务 Push 的 SDKAppID。 | <a href="https://console.cloud.tencent.com/im/push-plugin-push-identifier">IM 控制台 > 推送服务 Push > 概览</a> |
+| appKey | String | 推送服务 Push 的客户端密钥。 |  |
+| businessId | number | IM 控制台分配的证书 ID。 |  |
+
+### 反注册关闭推送服务
+
+#### 接口
+``` tsx
+unRegisterPush(): Promise<TIMPushResult>;
+```
+
+### 设置推送 ID 标识 RegistrationID
+
+> **说明：**
+>
+> 如果您调用此接口，请务必在 `registerPush` 前调用。
+>
+
+#### 接口
+``` tsx
+setRegistrationID(registrationID: string): Promise<TIMPushResult>;
+```
+
+#### 参数说明：
+
+|参数|类型|说明|
+|---------|---------|---------|
+|registrationID|String|自定义的推送 ID 标识。|
+
+### 获取推送 ID 标识 RegistrationID
+
+> **说明：**
+>
+> 若您调用过 `setRegistrationID` 接口设置标识 ID，此接口将返回您设置的标识 ID，否则返回由 Push SDK 生成的随机值。
+>
+
+#### 接口
+``` tsx
+getRegistrationID(): Promise<TIMPushResult>;
+```
+
+### 添加 Push 监听器
+
+#### 接口
+``` tsx
+addPushListener(listener: TIMPushListener): void;
+```
+
+#### 参数说明：
+
+|参数|类型|说明|
+|---------|---------|---------|
+|listener|TIMPushListener|推送事件处理方法。|
+
+### 移除 Push 监听器
+
+#### 接口
+``` tsx
+removePushListener(listener: TIMPushListener): void;
+```
+
+#### 参数说明：
+
+|参数|类型|说明|
+|---------|---------|---------|
+|listener|TIMPushListener|推送事件处理方法。|
+
+### 应用在前台时，开/关通知栏通知
+
+#### 接口
+``` tsx
+disablePostNotificationInForeground(disable: boolean): void;
+```
+
+#### 参数说明：
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| disable | boolean | 应用在前台时，开/关通知栏通知，默认关闭：<br>- true: 应用在前台时，关闭通知栏通知。<br>- false: 应用在前台时，开启通知栏通知。 |
+
+## TIMPushListener 接口概览
+
+|API|描述|
+|---------|---------|
+|onRecvPushMessage|收到 Push 消息。|
+|onRevokePushMessage|收到 Push 消息撤回的通知。|
+|onNotificationClicked|点击通知栏消息回调。|
+
+### 接口详情
+
+#### 成员函数说明
+
+##### onMessageReceived(message: TIMPushMessage): void;
+
+收到 Push 消息，message 消息。
+
+##### onRevokePushMessage(messageID: string): void;
+
+收到 Push 消息撤回的通知，messageID 消息唯一标识。
+
+##### onNotificationClicked(ext: string): void;
+
+点击通知栏消息回调。
+
+## TIMPushResult 接口概览
+
+|字段|描述|类型|
+|---------|---------|---------|
+|code|错误码|number|
+|message|错误描述|string|
+|data|返回值|unknown|

package/resource/knowledge/push/api-reference/ios.md

@@ -0,0 +1,537 @@
+本文介绍 TIMPush iOS SDK 的客户端 API，包括 `TIMPushManager`、`TIMPushListener`、`TIMPushDelegate`、`TIMPushMessage`、回调类型和错误码。
+
+## API 概览
+
+### TIMPushManager
+
+`TIMPushManager` 是 TIMPush iOS SDK 的推送服务管理类，用于注册推送服务、管理 `RegistrationID`、配置前台通知展示、添加监听器，以及在 Notification Service Extension 中统计推送抵达。
+
+|API|说明|
+|---------|---------|
+|registerPush:appKey:succ:fail:|注册推送服务。|
+|unRegisterPush:fail:|反注册推送服务。|
+|getRegistrationID:|获取当前推送注册标识。|
+|setRegistrationID:callback:|设置自定义推送注册标识。|
+|disablePostNotificationInForeground:|设置 App 前台收到推送时是否展示通知。|
+|addPushListener:|添加 Push 监听器。|
+|removePushListener:|移除 Push 监听器。|
+|handleNotificationServiceRequest:appGroupID:callback:|在 Notification Service Extension 中处理推送请求，用于统计推送抵达。|
+
+### TIMPushListener
+
+`TIMPushListener` 是 Push 事件监听协议。实现该协议后，可以接收推送消息、推送撤回和通知点击事件。协议未标注 `@optional`，实现时需同时实现全部三个方法。
+
+|API|说明|
+|---------|---------|
+|onRecvPushMessage:|收到 Push 消息。|
+|onRevokePushMessage:|收到 Push 消息撤回通知。|
+|onNotificationClicked:|收到通知栏消息点击回调。|
+
+### TIMPushDelegate
+
+`TIMPushDelegate` 是离线推送证书配置与点击事件处理协议。该协议继承自 `UIApplicationDelegate`，所有方法均为可选方法。
+
+|API|说明|
+|---------|---------|
+|businessID|返回离线推送证书 ID。|
+|applicationGroupID|返回主 App 与 Notification Service Extension 共享的 App Group ID。|
+|onRemoteNotificationReceived:|自定义处理收到的远程推送。|
+|navigateToBuiltInChatViewController:groupID:|处理通知点击后的页面跳转。|
+
+## 回调类型
+
+### TIMPushCallback
+
+不携带返回值的通用成功回调。
+
+#### 声明
+``` objectivec
+typedef void(^TIMPushCallback)(void);
+```
+
+### TIMPushValueCallback
+
+携带字符串返回值的回调。
+
+#### 声明
+``` objectivec
+typedef void(^TIMPushValueCallback)(NSString *value);
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`value`|`NSString *`|回调返回的字符串值。|
+
+### TIMPushSuccessCallback
+
+注册推送服务成功时触发的回调。
+
+#### 声明
+``` objectivec
+typedef void(^TIMPushSuccessCallback)(NSData *deviceToken);
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`deviceToken`|`NSData *`|APNs 返回的设备令牌。|
+
+### TIMPushFailedCallback
+
+接口调用失败时触发的回调。
+
+#### 声明
+``` objectivec
+typedef void(^TIMPushFailedCallback)(int code, NSString *desc);
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`code`|`int`|错误码。|
+|`desc`|`NSString *`|错误描述。|
+
+### TIMPushCallExperimentalAPISucc
+
+实验性 API 调用成功时触发的回调。
+
+#### 声明
+``` objectivec
+typedef void(^TIMPushCallExperimentalAPISucc)(NSObject *object);
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`object`|`NSObject *`|实验性 API 返回的数据对象。具体类型由 API 定义决定。|
+
+### TIMPushNotificationExtensionCallback
+
+Notification Service Extension 处理推送请求后触发的回调。
+
+#### 声明
+``` objectivec
+typedef void(^TIMPushNotificationExtensionCallback)(UNNotificationContent *content);
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`content`|`UNNotificationContent *`|处理后的通知内容。|
+
+#### 可用性
+
+iOS 10.0 及以上版本可用。
+
+## TIMPushManager
+
+### registerPush:appKey:succ:fail:
+
+注册 TIMPush 推送服务。
+
+#### 声明
+``` objectivec
++ (void)registerPush:(int)sdkAppId
+              appKey:(NSString *)appKey
+                succ:(TIMPushSuccessCallback)successCallback
+                fail:(TIMPushFailedCallback)failedCallback;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`sdkAppId`|`int`|应用的 SDKAppID。|
+|`appKey`|`NSString *`|控制台分配的 Push Key。独立 Push 场景需传入该参数；已集成 IM 或 TUIKit 产品时，请在登录成功回调中调用本接口，并将该参数设置为 `nil`。Chat Key 仅用于 Chat 登录，不要作为 `appKey` 传入。|
+|`successCallback`|`TIMPushSuccessCallback`|注册成功回调。回调携带 APNs 返回的 `deviceToken`。|
+|`failedCallback`|`TIMPushFailedCallback`|注册失败回调。回调携带错误码和错误描述。|
+
+#### 说明
+
+调用该接口前，请确保用户已同意 App 的隐私政策，并已获得通知授权。注册成功后，SDK 会建立当前设备与推送服务之间的绑定关系。
+
+如果需要自定义 `RegistrationID`，请先调用 `setRegistrationID:callback:`，再调用本接口注册推送服务。
+
+#### 可用性
+
+该接口不支持在 App Extension 中调用。
+
+### unRegisterPush:fail:
+
+反注册推送服务。
+
+#### 声明
+``` objectivec
++ (void)unRegisterPush:(TIMPushCallback)successCallback
+                  fail:(TIMPushFailedCallback)failedCallback;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`successCallback`|`TIMPushCallback`|反注册成功回调。|
+|`failedCallback`|`TIMPushFailedCallback`|反注册失败回调。回调携带错误码和错误描述。|
+
+#### 说明
+
+用户退出登录时，可以调用该接口关闭当前用户或当前设备的推送服务。
+
+如果您使用 `TUILogin` 提供的 `login` 和 `logout` 能力，无需额外调用该接口。
+
+#### 可用性
+
+该接口不支持在 App Extension 中调用。
+
+### getRegistrationID:
+
+获取当前推送注册标识。
+
+#### 声明
+``` objectivec
++ (void)getRegistrationID:(TIMPushValueCallback)callback;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`callback`|`TIMPushValueCallback`|获取成功回调。回调返回当前推送标识。|
+
+#### 说明
+
+回调返回值取决于接入场景：
+- 独立 Push 场景：返回 SDK 生成的 `registrationID`（设备标识），卸载重装后可能变化。
+
+- Chat / TUIKit 场景：返回当前 Chat 登录的 `userID`。
+
+   请在 `registerPush:appKey:succ:fail:` 成功回调之后再调用本接口，否则可能拿不到值。控制台或服务端发送测试消息时，使用该返回值定位设备或用户。
+
+#### 可用性
+
+该接口不支持在 App Extension 中调用。
+
+### setRegistrationID:callback:
+
+设置推送注册标识。
+
+#### 声明
+``` objectivec
++ (void)setRegistrationID:(NSString *)registrationID
+                 callback:(TIMPushCallback)callback;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`registrationID`|`NSString *`|自定义推送注册标识。|
+|`callback`|`TIMPushCallback`|设置完成回调。|
+
+#### 说明
+
+如果业务需要使用自定义 `RegistrationID` 向指定设备推送消息，请在调用 `registerPush:appKey:succ:fail:` 之前调用该接口。
+
+#### 可用性
+
+该接口不支持在 App Extension 中调用。
+
+### disablePostNotificationInForeground:
+
+设置 App 前台收到推送时是否展示通知。
+
+#### 声明
+``` objectivec
++ (void)disablePostNotificationInForeground:(BOOL)disable;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`disable`|`BOOL`|`YES` 表示关闭前台通知展示；`NO` 表示开启前台通知展示。|
+
+#### 说明
+
+App 处于前台时，SDK 收到在线推送后默认会展示通知。如果业务需要自行处理在线推送消息，可以将该参数设置为 `YES`。
+
+#### 可用性
+
+该接口可在主 App 中调用，未标注 App Extension 限制。
+
+#### Swift 名称
+``` swift
+disablePostNotificationInForeground(disable:)
+```
+
+### addPushListener:
+
+添加 Push 监听器。
+
+#### 声明
+``` objectivec
++ (void)addPushListener:(id<TIMPushListener>)listener;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`listener`|`id<TIMPushListener>`|Push 监听器对象。|
+
+#### 说明
+
+添加监听器后，SDK 会通过 `TIMPushListener` 回调 Push 消息、撤回通知和通知点击事件。
+
+#### Swift 名称
+``` swift
+addPushListener(listener:)
+```
+
+#### 可用性
+
+该接口不支持在 App Extension 中调用。
+
+### removePushListener:
+
+移除 Push 监听器。
+
+#### 声明
+``` objectivec
++ (void)removePushListener:(id<TIMPushListener>)listener;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`listener`|`id<TIMPushListener>`|需要移除的 Push 监听器对象。|
+
+#### 说明
+
+不再需要接收 Push 事件时，请调用该接口移除监听器。
+
+#### Swift 名称
+``` swift
+removePushListener(listener:)
+```
+
+#### 可用性
+
+该接口不支持在 App Extension 中调用。
+
+### handleNotificationServiceRequest:appGroupID:callback:
+
+在 Notification Service Extension 中处理推送请求。
+
+#### 声明
+``` objectivec
++ (void)handleNotificationServiceRequest:(UNNotificationRequest *)request
+                              appGroupID:(NSString *)appGroupID
+                                callback:(TIMPushNotificationExtensionCallback)callback;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`request`|`UNNotificationRequest *`|`UNNotificationServiceExtension` 接收到的通知请求。|
+|`appGroupID`|`NSString *`|主 App 与 Notification Service Extension 共享的 App Group ID。|
+|`callback`|`TIMPushNotificationExtensionCallback`|处理完成回调。回调携带处理后的通知内容。|
+
+#### 说明
+
+该接口用于统计 TIMPush 的推送抵达率。仅支持在 Notification Service Extension 的 `didReceiveNotificationRequest:withContentHandler:` 方法中调用。
+
+使用该接口前，请完成以下配置：
+1. 在主 App 的 Capability 中配置 App Groups 能力。
+
+2. 在 AppDelegate 中实现 `TIMPushDelegate` 的 `applicationGroupID` 方法，返回 App Group ID。
+
+3. 确保主 App 与 Notification Service Extension 使用同一个 App Group ID。
+
+#### Swift 名称
+``` swift
+handleNotificationServiceRequest(request:appGroupID:callback:)
+```
+
+## TIMPushListener
+
+`TIMPushListener` 协议未标注 `@optional`，实现该协议时需同时实现 `onRecvPushMessage:`、`onRevokePushMessage:` 和 `onNotificationClicked:` 三个方法。
+
+三个回调的触发时机如下：
+
+|回调|触发时机|
+|---------|---------|
+|`onRecvPushMessage:`|App 在线时，收到带 `offlinePushInfo` 的 IM 消息时触发。|
+|`onRevokePushMessage:`|App 在线时，收到消息撤回通知时触发。|
+|`onNotificationClicked:`|用户点击通知栏消息时触发。包含 App 离线时由 APNs / Notification Service Extension 下发、点击后拉起 App 的场景。|
+
+### onRecvPushMessage:
+
+App 在线时，收到带 `offlinePushInfo` 的 IM 消息时触发。App 进程已退出时本回调不会触发。
+
+#### 声明
+``` objectivec
+- (void)onRecvPushMessage:(TIMPushMessage *)message;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`message`|`TIMPushMessage *`|Push 消息对象。|
+
+### onRevokePushMessage:
+
+App 在线时，收到消息撤回通知时触发。App 进程已退出时本回调不会触发。
+
+#### 声明
+``` objectivec
+- (void)onRevokePushMessage:(NSString *)messageID;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`messageID`|`NSString *`|被撤回消息的唯一标识。|
+
+### onNotificationClicked:
+
+用户点击通知栏消息时触发。无论 App 当时在前台、后台还是已退出（点击通知拉起 App），都会触发。需要先在腾讯云控制台将推送证书的「点击后续动作」配置为「打开应用内指定页面」，并保持默认填充值。
+
+#### 声明
+``` objectivec
+- (void)onNotificationClicked:(NSString *)ext;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`ext`|`NSString *`|离线消息透传字段。|
+
+## TIMPushDelegate
+
+`TIMPushDelegate` 用于配置离线推送证书，以及接管远程推送和通知点击后的跳转处理。该协议继承自 `UIApplicationDelegate`，所有方法均为可选方法。
+
+### businessID
+
+返回离线推送证书 ID。
+
+#### 声明
+``` objectivec
+- (int)businessID;
+```
+
+#### 返回值
+
+IM 控制台分配的离线推送证书 ID。
+
+#### 说明
+
+请在 AppDelegate 中实现该方法，返回 IM 控制台分配的离线推送证书 ID。
+
+证书 ID 需要与当前运行环境对应。开发环境证书 ID 适用于 Xcode Debug 调试；生产环境证书 ID 适用于 Archive 后的 Release 包测试或发布。
+
+### applicationGroupID
+
+返回主 App 与 Notification Service Extension 共享的 App Group ID。
+
+#### 声明
+``` objectivec
+- (NSString *)applicationGroupID;
+```
+
+#### 返回值
+
+主 App 与 Notification Service Extension 共享的 App Group ID。
+
+#### 说明
+
+请在 AppDelegate 中实现该方法。当您需要统计 iOS 10 及以上版本推送抵达率时，建议实现该方法，并返回已配置的 App Group ID。该值需与 `handleNotificationServiceRequest:appGroupID:callback:` 传入的 `appGroupID` 保持一致。
+
+### onRemoteNotificationReceived:
+
+自定义处理收到的远程推送。该方法在 App 在线收到远程推送，或离线时用户点击通知栏通知时触发。
+
+#### 声明
+``` objectivec
+- (BOOL)onRemoteNotificationReceived:(nullable NSString *)notice;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`notice`|`NSString * _Nullable`|远程推送通知内容。|
+
+#### 说明
+
+如需自定义解析远程推送通知，请在 AppDelegate 中实现该方法。
+
+#### 返回值
+
+返回 `YES` 表示业务已自行处理该推送，TIMPush 不再执行内置的 TUIKit 离线推送解析逻辑。
+
+返回 `NO` 表示 TIMPush 继续执行内置的 TUIKit 离线推送解析逻辑，并继续回调 `navigateToBuiltInChatViewController:groupID:`。
+
+### navigateToBuiltInChatViewController:groupID:
+
+处理通知点击后的页面跳转。
+
+#### 声明
+``` objectivec
+- (void)navigateToBuiltInChatViewController:(nullable NSString *)userID
+                                    groupID:(nullable NSString *)groupID;
+```
+
+#### 参数
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`userID`|`NSString * _Nullable`|单聊用户 ID。|
+|`groupID`|`NSString * _Nullable`|群聊 ID。|
+
+#### 说明
+
+TIMPush 会从离线推送中解析 `userID` 和 `groupID`。如果 `groupID` 不为空，表示当前点击的是群聊离线消息；如果 `groupID` 为空且 `userID` 不为空，表示当前点击的是单聊离线消息。
+
+#### Swift 名称
+``` swift
+navigateToBuiltInChatViewController(userID:groupID:)
+```
+
+## TIMPushMessage
+
+`TIMPushMessage` 表示 Push 消息对象。
+
+### 属性
+
+|属性|类型|说明|
+|---------|---------|---------|
+|`title`|`NSString *`|离线推送标题。|
+|`desc`|`NSString *`|离线推送内容。|
+|`ext`|`NSString *`|离线推送透传内容。|
+|`messageID`|`NSString *`|消息唯一标识 ID。|
+
+## 错误码
+
+`TIMPushErrorCode` 定义 TIMPush SDK 的业务错误码。
+
+|错误码|枚举值|说明|
+|---------|---------|---------|
+|`TIMPushErrorUndefinedCode`|`-1`|未知错误。|
+|`TIMPushErrorNotLogined`|`800001`|注册 Push 前未登录 IM 账号。|
+|`TIMPushErrorInvalidSdkAppId`|`800002`|注册 Push 参数 `sdkAppId` 不合法。|
+|`TIMPushErrorRegisterPushInitFailed`|`800003`|初始化 SDK 失败。|
+|`TIMPushErrorCallExperimentalApiFailed`|`800015`|实验性 API 调用失败。|
+|`TIMPushErrorNotificationAuthorizationDenied`|`800016`|用户拒绝通知授权。|
+|`TIMPushErrorHttpsRequestFailed`|`800017`|HTTPS 请求失败。|