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