接口文档

最近更新时间:2019-08-23 17:36:17

所有 API 接口的包名路径前缀都是:com.tencent.android.tpush,其中有以下几个重要的对外提供接口的类名,如下表所示:

类名 说明
XGPushManager Push 服务推送
XGPushConfig Push 服务配置项接口
XGPushBaseReceive 接收消息和结果反馈的 Receiver,需要开发者在 AndroidManifest.xml 自主完成静态注册

启动与注册

  • App 只有在完成腾讯移动推送的启动与注册后才可以腾讯移动推送 SDK 提供 Push 服务,在这之前请确保配置 AccessId 和 AccessKey。
  • 新版的 SDK 已经将启动腾讯移动推送和 App 注册统一集成在注册接口中,即只需调用注册接口便默认完成启动和注册操作。
  • 注册成功后,会返回设备 Token,Token 用于标识设备唯一性,同时也是腾讯移动推送维持与后台连接的唯一身份标识。关于如何获取 Token 请参考 获取 Token

注册接口通常提供简版和带 callback 版本的接口,请根据业务需要决定选择接口。

设备注册

接口说明

普通注册只注册当前设备,后台能够针对不同的设备 Token 发送推送消息,有2个版本的 API 接口。

public static void registerPush(Context context)
说明:

这种注册方式,不支持推送账号。

参数说明

context:当前应用上下文对象,不能为 null。

示例代码

XGPushManager.registerPush(getApplicationContext());

接口说明

为方便用户获取注册是否成功的状态,提供带 callback 的版本。

public static void registerPush(Context context,
final XGIOperateCallback callback)

参数说明

  • context:当前应用上下文对象,不能为 null。
  • callback:callback 调用,主要包括操作成功和失败的回调,不能为 null。

示例代码

XGPushManager.registerPush(this, new XGIOperateCallback() {
@Override
public void onSuccess(Object data, int flag) {
Log.d("TPush", "注册成功,设备token为:" + data);
}
@Override
public void onFail(Object data, int errCode, String msg) {
Log.d("TPush", "注册失败,错误码:" + errCode + ",错误信息:" + msg);
}
})

绑定账号注册

接口说明

绑定账号注册,指在绑定设备注册的基础上,使用指定的账号(一个账号不能在多个设备登录)注册 App,这样可以通过后台向指定的账号发送推送消息,有2个版本的 API 接口。

启动并注册App,同时绑定账号,推荐有账号体系的App使用(此接口会覆盖设备之前绑定过的账号,仅当前注册的账号生效)
void bindAccount(Context context, String account, XGIOperateCallback callback)

启动并注册APP,同时绑定账号,推荐有账号体系的App使用(此接口会覆盖设备之前绑定过的账号,仅当前注册的账号生效,无注册回调)    
void bindAccount(Context context, final String account)

启动并注册App,同时绑定账号,推荐有账号体系的App使用(此接口保留之前的账号,只做增加操作,一个token下最多只能有10个账号超过限制会自动顶掉之前绑定的账号,有注册回调)
void appendAccount(Context context, String account, XGIOperateCallback callback)

启动并注册App,同时绑定账号,推荐有账号体系的App使用(此接口保留之前的账号,只做增加操作,一个token下最多只能有10个账号超过限制会自动顶掉之前绑定的账号,无注册回调)
void appendAccount(Context context, final String account)    
说明:

这里的账号可以是邮箱、QQ 号、手机号、用户名等任意类别的业务账号。

参数说明

  • context:当前应用上下文对象,不能为 null。
  • account:账号。

示例代码

XGPushManager.bindAccount(getApplicationContext(),"test");

账号解绑

接口说明

对已绑定的账号进行解绑。

//解绑指定账号(有注册回调)

void delAccount(Context context, final String account, XGIOperateCallback callback)    

//解绑指定账号(无注册回调)

void delAccount(Context context, final String account )
说明:

账号解绑只是解除 Token 与 App 账号的关联,若使用全量/标签/Token 推送仍然能收到通知/消息。

参数说明

  • context:当前应用上下文对象,不能为 null。
  • account:账号。

示例代码

XGPushManager.delAccount(getApplicationContext(),"test");

获取注册结果

有2种途径可以获取注册是否成功。

使用 Callback 版本的注册接口
XGIOperateCallback 类提供注册成功或失败的处理接口,请参考注册接口里面的示例。

示例代码

/**
* 操作回调接口
*/
public interface XGIOperateCallback {
/**
* 操作成功时的回调。
* @param data 操作成功的业务数据,如注册成功时的token信息等。
* @param flag 标记码
*/
public void onSuccess(Object data, int flag);
/**
* 操作失败时的回调
* @param data 操作失败的业务数据
* @param errCode 错误码
* @param msg 错误信息
*/
public void onFail(Object data, int errCode, String msg);
}

重载 XGPushBaseReceiver
可通过重载 XGPushBaseReceiver 的 onRegisterResult 方法获取。

说明:

重载的 XGPushBaseReceiver 需要配置在 AndroidManifest.xml,请参考下文 消息配置

示例代码

/**
* 注册结果
*
* @param context
* APP上下文对象
* @param errorCode
* 错误码,{@link XGPushBaseReceiver#SUCCESS}表示成功,其它表示失败
* @param registerMessage
* 注册结果返回
*/

类方法列表

方法名 返回值 默认值 描述
getToken() String 设备的 Token,即设备唯一识别 ID
getAccessId() long 0 获取注册的 AccessId
getAccount String 获取注册绑定的账号
getTicket() String 登录态票据
getTicketType() short 0 票据类型

反注册

接口说明

当用户已退出或 App 被关闭,不再需要接收推送时,可以取消注册 App,即反注册。(一旦设备反注册,直到这个设备重新注册成功期间内,下发的消息该设备都无法收到)

public static void unregisterPush(Context context)

参数说明

context: App 的上下文对象。

示例代码

XGPushManager.unregisterPush(this);

反注册结果

可通过重载 XGPushBaseReceiver的onUnregisterResult 方法获取。

说明:

  • 反注册操作切勿过于频繁,可能会造成后台同步延时。
  • 切换账号无需反注册,多次注册自动会以最后一次为准。

示例代码

<pre class="brush:cpp;">/**
* 反注册结果
*
* @param context
* APP上下文对象
* @param errorCode
* 错误码,{@link XGPushBaseReceiver#SUCCESS}表示成功,其它表示失败
*/
@Override
public void onUnregisterResult(Context context, int errorCode) {

}
</pre>

通知和消息

腾讯移动推送推送服务主要提供2种推送格式:推送通知和应用内消息命令,二者存在一定的区别。

推送通知(展现在通知栏)

指的是在设备的通知栏展示的内容,由腾讯移动推送 SDK 完成所有的操作,App 可以监听通知被打开的行为,即在前台下发的通知,无需 App 做任何处理,默认会展示在通知栏。

说明:

  • 成功注册腾讯移动推送服务后,通常不需要任何设置便可下发通知。
  • 通常来说,结合自定义通知样式,常规的通知,能够满足大部分业务需求,如果需要更灵活的方式,请考虑使用消息。

应用内消息命令(消息不展示到通知栏)

指的是由腾讯移动推送下发给 App 的内容,需要 App 继承 XGPushBaseReceiver 接口实现并自主处理所有操作过程,也就是说,下发的消息默认是不会展示在通知栏的,腾讯移动推送只负责将消息从腾讯移动推送服务器下发到 App 这个过程,不负责消息的处理逻辑,需要 App 自己实现。

  • 消息指的是由开发者通过前台或后台脚本下发的文本消息,腾讯移动推送只负责将消息传递给 App,App 完全自主负责消息体的处理。
  • 消息具有灵活性强和高度定制性的特点,更适合 App 自主处理个性化业务需求,例如下发 App 配置信息、自定义处理消息的存储和展示等。

消息配置

请自行继承 XGPushBaseReceiver ,并且在配置文件中配置如下内容:

示例代码

<receiver android:name="com.tencent.android.xg.cloud.demo.MessageReceiver">
            <intent-filter>
                <!-- 接收消息透传 -->
                <action android:name="com.tencent.android.xg.vip.action.PUSH_MESSAGE" />
                <!-- 监听注册、反注册、设置/删除标签、通知被点击等处理结果 -->
                <action android:name="com.tencent.android.xg.vip.action.FEEDBACK" />
            </intent-filter>
        </receiver>

获取应用内消息

开发者在前台下发消息,需要 App 继承 XGPushBaseReceiver 重载 onTextMessage 方法接收,成功接收后,再根据特有业务场景进行处理。

说明:

请确保在 AndroidManifest.xml 已经注册过该 receiver,即设 YOUR_PACKAGE.XGPushBaseReceiver。

public void onTextMessage(Context context,
XGPushTextMessage message)

参数说明

  • context:应用当前上下文。
  • message:接收到消息结构体。

类方法列表

方法名 返回值 默认值 描述
getContent() String 消息正文内容,通常只需要下发本字段即可
getCustomContent() String 消息自定义 key-value
getTitle() String 消息标题(从前台下发应用内消息字中的描述不属于标题)

本地通知

本地通知由用户自定义设置,保存在本地。当应用打开,腾讯移动推送 Service 会根据网络心跳,判断当前是否有通知(5分钟一次), 本地通知需要 Service 开启才能弹出,可能存在5分钟左右延时。(当设置的时间小于当前设备时间通知弹出)

示例代码

//新建本地通知
XGLocalMessage local_msg = new XGLocalMessage();

//设置本地消息类型,1:通知,2:消息

local_msg.setType(1);

// 设置消息标题

local_msg.setTitle("qq");

//设置消息内容

local_msg.setContent("ww");

//设置消息日期,格式为:20140502

local_msg.setDate("20140930");

//设置消息触发的小时(24小时制),例如:22代表晚上10点

local_msg.setHour("19");

//获取消息触发的分钟,例如:05代表05分

local_msg.setMin("31");

//设置消息样式,默认为0或不设置

local_msg.setBuilderId(0);

//设置动作类型:1打开activity或app本身,2打开浏览器,3打开Intent ,4通过包名打开应用

local_msg.setAction_type(1);

//设置拉起应用页面

local_msg.setActivity("com.qq.xgdemo.SettingActivity");
// 设置URL

local_msg.setUrl("http://www.baidu.com");

// 设置Intent

local_msg.setIntent("intent:10086#Intent;scheme=tel;action=android.intent.action.DIAL;S.key=value;end");

// 是否覆盖原先build_id的保存设置。1覆盖,0不覆盖

local_msg.setStyle_id(1);

// 设置音频资源

local_msg.setRing_raw("mm");

// 设置key,value

HashMap<String, Object> map = new HashMap<String, Object>();

map.put("key", "v1");

map.put("key2", "v2");

local_msg.setCustomContent(map);

// 设置下载应用URL

local_msg.setPackageDownloadUrl("http://softfile.3g.qq.com:8080/msoft/179/1105/10753/MobileQQ1.0(Android)_Build0198.apk");

//添加通知到本地     XGPushManager.addLocalNotification(context,local_msg);

获取设备 Token

Token 是腾讯移动推送保持与后台长连接的唯一身份标识,是 App 接收消息的唯一 ID,只有设备注册成功后才能获取 Token,可以有以下方法获。(腾讯移动推送的 Token 在应用卸载重新安装的时候有可能会变。)

通过带 callback 的注册接口获取

带 XGIOperateCallback 的注册接口的 onSuccess(Object data, int flag) 方法中,参数 data 便是 Token,具体可参考注册接口的相关示例。

重载 XGPushBaseReceiver

重载 XGPushBaseReceiver 的 onRegisterResult (Context context, int errorCode, XGPushRegisterResult registerMessage) 方法,通过参数 registerMessage 提供的 getToken 接口获取,具体可参考“获取注册结果”章节。

XGPushConfig.getToken(context)

当设备一旦注册成功后,便会将 Token 存储在本地,之后可通过 XGPushConfig.getToken(context) 接口获取。

获取通知

接口说明

通知的下发和展示完全是由腾讯移动推送 SDK 控制的,但有的开发者需要在本地存储被展示过的通知内容,可以通过重载 XGPushBaseReceiver 的 onNotificationShowedResult(Context, XGPushShowedResult) 方法实现。其中,XGPushShowedResult 对象提供读取通知内容的接口。

public abstract void onNotificationShowedResult(Context context,XGPushShowedResult notifiShowedRlt); 

参数说明

  • context:当前应用上下文。
  • notifiShowedRlt: 被展示的通知对象。

获取消息点击结果

通知效果监听和自定义 key-value

使用腾讯移动推送 SDK 内置的 activity 展示页面,默认已经统计通知/消息的抵达量、通知的点击和清除动作。但如果开发者要监听这些事件,需要按照以下方法嵌入代码。

说明:

如果需要统计由腾讯移动推送推送引起的打开 App 操作或获取下发的自定义 key-value,需要开发者在所有(或被打开)的 Activity的onResume() 调用以下方法。

接口说明

onNotificationClickedResult(Context context, XGPushClickedResult notifiClickedRlt); 

参数说明

activity:被打开 activity 上下文。

返回值

XGPushClickedResult:通知被打开的对象,如果该 activity 是由腾讯移动推送的通知引起打开动作的,返回XGPushClickedResult,否则返回 null。

类方法列表

方法名 返回值 默认值 描述
getMsgId() long 0 消息 ID
getTitle() String 通知标题
getContent() String 通知正文内容
getActivityName() String 被打开的页面名称
getCustomContent() String 自定义 key-value,JSON 字符串同时,在 Activity 的 onPause() 调用以下方法

标签

预置标签

目前腾讯移动推送提供两类预置标签:

  • 地理位置(省一级)。
  • 应用版本号。
  • 预置标签会在 SDK 内部自动上报。

设置自定义标签

接口说明

开发者可以针对不同的用户设置标签,然后在前台根据标签名群发通知。 一个应用最多有10000个 tag, 每个 Token 在一个应用下最多100个 tag, tag 中不准包含空格。

public static void setTag(Context context, String tagName) 

参数说明

  • context:Context 对象
  • tagName:待设置的标签名称,不能为 null 或空。

处理结果

可通过重载 XGPushBaseReceiver 的 onSetTagResult 方法获取。

示例代码

XGPushManager.setTag(this, "male"); 

设置多个标签

接口说明

一次设置多个标签,会覆盖这个设备之前设置的标签。

public static void setTags(Context context, String operateName, Set<String> tags) 

参数说明

  • context:Context 对象。
  • operateName:用户定义的操作名称,回调结果会原样返回,用于标识回调属于哪次操作。
  • tags:标签名集合,每个标签是一个 String。限制:每个 tag 不能超过40字节(超过会抛弃),不能包含空格(含有空格会删除空格)。最多设置1000个 tag,超过部分会抛弃。

处理结果

可通过重载 XGPushBaseReceiver的onSetTagResult 方法获取。

示例代码

String[] tags = "tag1 tag2".split(" ");
Set<String> tagsSet = new HashSet<>(Arrays.asList(tags));
XGPushManager.setTags(getApplicationContext(), "setTags:" + System.currentTimeMillis(), tagsSet); 

增加多个标签

接口说明

一次设置多个标签,会覆盖这个设备之前设置的标签。

  • 如果新增的标签的格式为 "test:2 level:2",则会删除这个设备的全部历史标签,再新增 test:2 和 level。
  • 如果新增的标签有部分不带:号,如 "test:2 level",则会删除这个设备的全部历史标签,再新增 test:2 和 level 标签。
说明:

  • 新增的 tags 中,:号为后台关键字,请根据具体的业务场景使用。
  • 此接口调用的时候需要间隔一段时间(建议大于5s),否则可能造成更新失败。
public static void addTags(Context context, String operateName, Set<String> tags) 

参数说明

  • context:Context 对象。
  • operateName:用户定义的操作名称,回调结果会原样返回,用于标识回调属于哪次操作。
  • tags:标签名集合,每个标签是一个 String。限制:每个 tag 不能超过40字节(超过会抛弃),不能包含空格(含有空格会删除空格)。最多设置1000个 tag,超过部分会抛弃。

处理结果

可通过重载 XGPushBaseReceiver的onSetTagResult 方法获取。

示例代码

String[] tags = "tag1 tag2".split(" ");
Set<String> tagsSet = new HashSet<>(Arrays.asList(tags));
XGPushManager.addTags(getApplicationContext(), "addTags:" + System.currentTimeMillis(), tagsSet);

删除标签

接口说明

开发者删除用户标签数据。

public static void deleteTag(Context context, String tagName) 

参数说明

  • context:Context 对象。
  • tagName:待设置的标签名称,不能为 null 或空。

处理结果

可通过重载 XGPushBaseReceiver的onDeleteTagResult 方法获取。

示例代码

XGPushManager.deleteTag (this, "male"); 

删除多个标签

接口说明

一次删除多个标签。

public static void deleteTags(Context context, String operateName, Set<String> tags)

参数说明

  • context:Context 对象。
  • operateName:用户定义的操作名称,回调结果会原样返回,用于标识回调属于哪次操作。
  • tags:标签名集合,每个标签是一个 String。限制:每个 tag 不能超过40字节(超过会抛弃),不能包含空格(含有空格会删除空格)。最多设置1000个tag,超过部分会抛弃。

处理结果

可通过重载 XGPushBaseReceiver的onSetTagResult 方法获取。

示例代码

String[] tags = "tag1 tag2".split(" ");
Set<String> tagsSet = new HashSet<>(Arrays.asList(tags));
XGPushManager.deleteTags(getApplicationContext(), "deleteTags:" + System.currentTimeMillis(), tagsSet);

清除所有标签

接口说明

清除这个设备的所有标签。

public static void cleanTags(Context context, String operateName)

参数说明

  • context:Context 对象。
  • operateName:用户定义的操作名称,回调结果会原样返回,用于标识回调属于哪次操作。

处理结果

可通过重载 XGPushBaseReceiver 的 onSetTagResult 方法获取。

示例代码

XGPushManager.cleanTags(getApplicationContext(), "cleanTags:" + System.currentTimeMillis());

配置接口

所有的配置相关接口在 XGPushConfig 类中,为了使配置及时生效,开发者需要保证配置接口在启动或注册腾讯移动推送之前被调用。

Debug 模式

接口说明

为保证数据的安全性,请在发布时确保已关闭 Debug 模式。

public static void enableDebug(Context context, boolean debugMode)

参数说明

  • context:App 上下文对象。
  • debugMode:默认为 false。如果要开启 Debug 日志,设为 true。

获取 Token

接口说明

Token 是一个设备的身份识别 ID,由服务器根据设备属性随机产生并下发到本地,同一 App 在不同设备上的 Token 是不同的。

public static String getToken(Context context)
说明:

App 第一次注册会产生 Token,之后一直存在手机上,不管以后注销注册操作,该 Token 一直存在,当 App 完全卸载重装了 Token 会发生变化。不同 App 之间的 Token 不一样。

参数说明

context:App 上下文对象。

返回值

成功时返回正常的 Token;失败时返回 null 或0。

设置 AccessID

接口说明

如果已在 AndroidManifest.xml 配置过,无需再次调用;如果二者都存在,则以本接口为准。

public static boolean setAccessId(Context context, long accessId)

参数说明

  • Context:对象。
  • accessId:前台注册得到的 accessId。

返回值

  • true:成功。
  • false:失败。
说明:

通过本接口设置的 accessId 会同时存储在文件中。

设置 AccessKey

接口说明

如果已在 AndroidManifest.xml 配置过,无需再次调用;如果二者都存在,则以本接口为准。

public static boolean accessKey(Context context, String accessKey) 

参数说明

  • Context:对象。
  • accessKey:前台注册得到的 accesskey。

返回值

  • true:成功。
  • false:失败。
说明:

通过本接口设置的 accessKey 会同时存储在文件中。