本文介绍 TIMPush Android SDK 的客户端 API，包括
TIMPushManager、TIMPushListener、TIMPushCallback、TIMPushMessage 和错误码。API 概览
TIMPushManager
TIMPushManager 是 TIMPush Android SDK 的推送服务管理类，用于注册推送服务、管理 RegistrationID、配置推送通道和前台通知展示，以及添加 Push 监听器。API | 说明 |
获取 TIMPushManager 管理器实例。 | |
注册推送服务。 | |
反注册关闭离线推送服务。 | |
获取推送唯一 ID 标识。 | |
自定义设置推送唯一 ID 标识。 | |
添加 Push 监听器。 | |
移除 Push 监听器。 | |
指定设备离线推送使用 FCM 通道。 | |
关闭 App 在前台时弹出通知栏。 |
TIMPushListener
TIMPushListener 是 Push 监听器抽象类。按需重写以下方法，即可接收 Push 消息、推送撤回和通知点击事件。API | 说明 |
收到 Push 消息。 | |
收到 Push 消息撤回通知。 | |
点击通知栏消息回调。 |
回调类型
TIMPushCallback
TIMPush 通用结果回调抽象类。接口调用成功时触发
onSuccess，失败时触发 onError。声明
public abstract class TIMPushCallback<T> {public void onSuccess(T data) {}public void onError(int errCode, String errMsg, T data) {}}
参数
参数 | 类型 | 说明 |
data | T | 成功或失败回调时返回的数据。 |
errCode | int | 失败回调时的错误码。 |
errMsg | String | 失败回调时的错误描述。 |
TIMPushManager
getInstance
获取
TIMPushManager 管理器实例。声明
public static TIMPushManager getInstance();
返回值
TIMPushManager 单例对象。后续 API 均通过该实例调用。registerPush
注册推送服务。
声明
public abstract void registerPush(Context context, int sdkAppId, String appKey, TIMPushCallback callback);
参数
参数 | 类型 | 说明 |
context | Context | Android 上下文对象。 |
sdkAppId | int | 应用的 sdkAppId。 |
appKey | String | 控制台分配的 appKey。 |
callback | TIMPushCallback | 注册结果回调。 |
说明
如果您单独使用推送服务，请正确传递
sdkAppId 和 appKey 两个参数，即可注册推送服务。如果您已经集成 IM 产品，请在 IM 登录成功后调用该接口，将
appKey 参数设置为 null，接入离线推送能力。unRegisterPush
反注册关闭离线推送服务。
声明
public abstract void unRegisterPush(TIMPushCallback callback);
参数
参数 | 类型 | 说明 |
callback | TIMPushCallback | 反注册结果回调。 |
getRegistrationID
获取推送唯一 ID 标识。
声明
public abstract void getRegistrationID(TIMPushCallback callback);
参数
参数 | 类型 | 说明 |
callback | TIMPushCallback | 获取结果回调。 |
说明
注册离线推送服务成功后，通过该接口可获取推送唯一 ID 标识，即
RegistrationID，然后可以根据 RegistrationID 向指定设备推送消息。RegistrationID 是设备的推送唯一标识 ID。默认注册推送服务成功后会自动生成，也支持用户自定义设置，提供用户根据 RegistrationID 向指定设备推送消息的能力，卸载重装会改变。setRegistrationID
自定义设置推送唯一 ID 标识。
声明
public abstract void setRegistrationID(String registrationID, TIMPushCallback callback);
参数
参数 | 类型 | 说明 |
registrationID | String | 自定义推送唯一标识 ID。 |
callback | TIMPushCallback | 设置结果回调。 |
说明
自定义设置设备使用的推送唯一标识 ID，即
RegistrationID，需要在注册推送服务之前调用。RegistrationID 是设备的推送唯一标识 ID。默认注册推送服务成功后会自动生成，也支持用户自定义设置，提供用户根据 RegistrationID 向指定设备推送消息的能力，卸载重装会改变。addPushListener
添加 Push 监听器。
声明
public abstract void addPushListener(TIMPushListener listener);
参数
参数 | 类型 | 说明 |
listener | TIMPushListener | Push 监听器对象。 |
removePushListener
移除 Push 监听器。
声明
public abstract void removePushListener(TIMPushListener listener);
参数
参数 | 类型 | 说明 |
listener | TIMPushListener | 需要移除的 Push 监听器对象。 |
forceUseFCMPushChannel
指定设备离线推送使用 FCM 通道。
声明
public abstract void forceUseFCMPushChannel(boolean enable);
参数
参数 | 类型 | 说明 |
enable | boolean | true 表示使用 FCM 通道；false 表示使用本机通道。 |
说明
需要在注册推送服务之前调用。常用于海外推送走 FCM 通道，例如海外小米手机走 FCM 通道。
disablePostNotificationInForeground
关闭 App 在前台时弹出通知栏。
声明
public abstract void disablePostNotificationInForeground(boolean disable);
参数
参数 | 类型 | 说明 |
disable | boolean | true 表示关闭；false 表示开启。 |
说明
推送 SDK 收到在线推送时，会自动向通知栏增加 Notification 提示。如果您想自己处理在线推送消息，可以调用该接口关闭自动弹通知栏提示的特性。
TIMPushListener
TIMPushListener 是 Push 监听器抽象类。基类已提供空实现，按需重写以下方法即可。三个回调的触发时机如下：
回调 | 触发时机 |
onRecvPushMessage | App 在线时，收到带 offlinePushInfo 的 IM 消息时触发。 |
onRevokePushMessage | App 在线时，收到消息撤回通知时触发。 |
onNotificationClicked | 用户点击通知栏消息时触发。包含 App 离线时由厂商通道（小米 / 华为 / OPPO / vivo / 荣耀 / 魅族 / FCM）下发、点击后拉起 App 的场景。 |
onRecvPushMessage
App 在线时，收到带
offlinePushInfo 的 IM 消息时触发。App 进程已退出时本回调不会触发。声明
public void onRecvPushMessage(TIMPushMessage message);
参数
参数 | 类型 | 说明 |
message | TIMPushMessage | Push 消息对象。 |
onRevokePushMessage
App 在线时，收到消息撤回通知时触发。App 进程已退出时本回调不会触发。
声明
public void onRevokePushMessage(String messageID);
参数
参数 | 类型 | 说明 |
messageID | String | 消息唯一标识。 |
onNotificationClicked
用户点击通知栏消息时触发。无论 App 当时在前台、后台还是已退出（点击通知拉起 App），都会触发。
声明
public void onNotificationClicked(String ext);
参数
参数 | 类型 | 说明 |
ext | String | 离线消息透传字段。 |
说明
需要先在腾讯云控制台将推送证书的「点击后续动作」配置为「打开应用内指定界面」，并保持默认填充值，否则本回调不会触发。
TIMPushMessage
TIMPushMessage 表示 Push 消息对象，实现 Serializable 接口。构造方法
声明
public TIMPushMessage();
属性
属性 | 类型 | 说明 |
title | String | 离线推送标题。 |
desc | String | 离线推送内容。 |
ext | String | 离线推送透传内容。 |
messageID | String | 消息唯一标识 ID。 |
方法
方法 | 返回类型 | 说明 |
setTitle(String title) | void | 设置离线推送标题。 |
getTitle() | String | 获取离线推送标题。 |
setDesc(String description) | void | 设置离线推送内容。 |
getDesc() | String | 获取离线推送内容。 |
setExt(String ext) | void | 设置离线推送透传内容。 |
getExt() | String | 获取离线推送透传内容。 |
setMessageID(String messageID) | void | 设置消息唯一标识 ID。 |
getMessageID() | String | 获取消息唯一标识 ID。 |
toString() | String | 返回消息对象的字符串描述。 |
错误码
TIMPushConstants 定义 TIMPush SDK 的业务错误码。错误码 | 枚举值 | 说明 |
ERR_INVALID_PARAM | 800000 | 参数不合法。 |
ERR_NOT_LOGINED | 800001 | 注册 Push 之前，未登录 IM 账号。 |
ERR_INVALID_SDK_APPID | 800002 | 注册 Push 参数 sdkAppID 不合法。 |
ERR_REGISTER_PUSH_INIT_FAILED | 800003 | 初始化 SDK 失败。 |
ERR_REGISTER_PUSH_CONNECT_FAILED | 800004 | 长链接建立失败。 |
ERR_REGISTER_PUSH_FAILED_BUILT_IN_DEVICE | 800005 | 本机通道注册推送失败。 |
ERR_REGISTER_PUSH_FAILED_TRY_FCM | 800006 | 本机通道注册推送失败后，尝试 FCM 通道注册失败。 |
ERR_REGISTER_PUSH_FAILED_DETECT_CHANNELS | 800007 | 探测所有通道失败。 |
ERR_REGISTER_PUSH_FAILED_TIMEOUT | 800008 | 注册推送服务超时。 |
ERR_REGISTER_TOKEN_EMPTY | 800009 | 注册推送 token 为空。 |
ERR_SET_PUSH_TOKEN_FAILED | 800010 | 给 SDK 设置 token 失败。 |
ERR_DISABLE_AUTO_REGISTER_PUSH_FAILED | 800011 | 关闭自动注册失败。 |
ERR_DISABLE_REQUEST_POST_NOTIFICATION_PERMISSION_FAILED | 800012 | 关闭推送权限请求失败。 |
ERR_CREATE_NOTIFICATION_CHANNEL_FAILED | 800013 | 创建通知 channel 失败。 |
ERR_SET_PUSH_CONFIG_FAILED | 800014 | 设置推送配置失败。 |
ERR_CALL_EXPERIMENTAL_API_FAILED | 800015 | 实验性接口调用失败。 |
ERR_SET_APP_LANGUAGE_FAILED | 800016 | 配置设备语言失败。 |
ERR_HTTPS_REQUEST_FAILED | 800017 | HTTPS 请求失败。 |
