分享到 :

Android_SDK使用说明

特别提示
Android SDK 1.8与1.4及以上版本兼容,与 1.3及以前版本不兼容。类名、接口和回调方式都有变化,因此不能通过替换jar文件的方式升级。建议开发者按照本文档的方式,重新配置SDK并添加对应的业务逻辑代码。

 

1. Andriod_SDK 简介

Android SDK以Jar包形式提供,封装了QQ登录的登录授权以及大部分OpenAPI及社交渠道的分享、邀请、请求礼物、挑战炫耀等API,移动应用只需要修改少量代码,即可快速实现QQ登录功能,并可调用平台提供的OpenAPI及社交渠道API的功能。

Android平台上的应用,要使用QQ互联提供的Android SDK,请先在QQ互联开放平台进行注册,获取appid和appkey。

主要提供的功能接口有:登录、注销、邀请好友、应用分享、获取用户信息、获取用户相册列表、发送分享、发表说说、上传图片、创建相册、设置QQ头像、增量授权、分享消息给QQ好友、发送请求、赠送礼物、发送挑战、炫耀等功能,Andriod_SDK_V1.8新增了发送带图微博, 更换了获取用户信息接口,更多详细信息请查看API列表

2. 下载Android SDK

请到SDK下载页面下载Android SDK和示例代码。

 

3. 创建工程及引用SDK源码文件

以下以eclipse为开发的IDE进行范例说明:

(1)创建一个工程,并把open-sdk.jar文件和mta_sdk_x.x.x.jar文件拷贝到libs(或lib)目录下,如下图所示:

引入jar

(2)将open-sdk.jar加入编译路径中。
具体的操作步骤为:选中open-sdk.jar,右键菜单中选择Build Path, 选择Add to Build Path,如下图所示:

加入编译路径

(3)将mta_sdk_x.x.x.jar加入编译路径中。
按照上面的方法,将mta_sdk_x.x.x.jar加入编译路径中。
在工程的Referenced Libraries目录下看到导入的jar包,说明已经成功将jar包加入build path,如下图所示:

引入成功

 

4. Andriod_SDK 使用说明

在使用Andriod_SDK时,主要有以下五个步骤:

Step1:给应用的AndroidManifest增加SDK需要的配置;

Step2:创建SDK的主要实现类的实例;

Step3:实现SDK接口回调;

Step4:access_token、openid的获取和使用;

Step5:调用OpenAPI。

 

4.1 配置AndroidManifest

在应用的AndroidManifest.xml增加配置的<application>节点下增加以下配置(注:不配置将会导致无法调用API);

 

其中,如果你已经添加了"android.permission.INTERNET"和"android.permission.ACCESS_NETWORK_STATE"权限,则无需重复添加。

而"你的AppId"则要替换成具体应用的AppId,例如你的AppId是"222222",则<data>标签应该是这样的:

 

4.2 创建实例

创建SDK主要实现类Tencent类的示例代码如下:

 

4.3 实现回调

所有的SDK接口调用,都会传入一个回调,用以接收SDK返回的调用结果。回调的主要接口有两种:

(1) IUiListener:调用SDK已经封装好的接口时,例如:登录、快速支付登录、应用分享、应用邀请等接口。

IUiListener的实现示例代码如下:

(2) IRequestListener:使用requestAsync、request等通用方法调用sdk未封装的接口时,例如上传图片、查看相册等。

IRequestListener的实现示例代码如下:

应用在调用SDK提供的接口时,将实现了对应回调接口的实例传入。当SDK的接口调用完成后,具体如登录、应用邀请和应用分享调用完成后,会回调传入的接口实例。

特别注意

应用调用Andriod_SDK接口时,如果要成功接收到回调,需要在调用接口的Activity的onActivityResult方法中增加如下代码:

4.4 access_token、openid的获取和使用

4.4.1获取access_token和openid

应用通过调用SDK的登录接口获取access_token和openid。登录接口的调用说明详见SDK包里的《Andriod_SDK_V1.8接口调用说明》中的"1.1登录"。

调用SDK的登录接口,用户登录成功后,会通过回调的方式返回一个json格式的字符串,在这个json字符串中会包含三个参数,分别是openid、access_token、expires_in。

返回参数说明如下表所示:

返回参数 参数说明
openid 用于唯一标识用户身份(每一个openid与QQ号码对应)。
access_token 用户进行应用邀请、分享、支付等基本业务请求的凭据。
expires_in access_token的有效时间,在有效期内可以发起业务请求,过期失效。

 

access_token的有效期为3个月,在有效期内,使用此token进行应用分享、邀请等操作都是可以正常完成的。超过这个时间,服务器会认为token已失效,需要重新登录。

4.4.2使用access_token和openid

应用在每次登录之后,都会获取到openid、access_token和expires_in,在调用SDK提供的接口时,后台会根据这三个参数来验证请求的合法性。

(1)如果应用已经走过登录流程,调用应用分享、邀请等接口,是不需要再将这三个参数传入到请求参数中去的,这是因为在登录成功后,SDK会自动将这几个参数保存在SDK的上下文中,在发送请求时,会自动为请求加上这些参数。

(2)如果应用不希望每次都走登录流程来使用SDK的功能,可以通过以下步骤来实现:

Step1:在首次登录成功后,将返回的openid、access_token、expires_in三个参数保存在本地(比如保存在sharedPreferrence)。其中expires_in参数在存储前需进行如下计算:

这样得出的就是token的失效日期。

Step2:在用户下次进入应用,发起应用分享等SDK调用之前,首先创建Tencent实例,然后取出之前保存的openid、access_token、expires_in(前面计算出来的值)的值。

Step3:调用Tencent类的setOpenId和setAccessToken方法。其中setOpenId的参数传入上一步取出的openid,setAccessToken的第一个参数传入上一步取出的access_token,第二个参数传入(上一步保存的token失效日期-当前系统时间)/1000。这里计算出的结果是当前保存的token的有效时间,如果结果小于或等于0,表示token已经过期,应该提示用户重新走登录流程。

免登录流程调用SDK接口的示例代码如下(省去了获取存储的变量的过程):

 

4.5 调用OpenAPI

SDK中Tencent类是对外提供功能接口的主要实现类,所有接口都通过Tencent类的实例来调用。

接口的详细调用说明,请参见SDK包中的《Andriod_SDK_V1.8接口调用说明》。

接口调用的详细示例,请参见SDK包中的sample\src\com\tencent\sample目录下的MainActivity.java文件。

4.6 混淆说明

如果应用需要混淆代码,为了保证SDK的正常使用,建议不要混淆SDK的jar包,如果仍要混淆,需要在混淆规则中加上下面几行配置:

 

5. 返回码说明

使用SDK时,所有结果都会通过回调返回给应用。在回调的结果中,会包含每次调用结果的返回码。正常情况下返回码为0,表示调用成功。如果返回码不为0,说明调用出错,需要根据返回码的值来定位错误原因。

常用返回码与错误信息的对照,如下表所示:

返回码 含义说明
-30001 由于网络质量抖动引起,如果持续时间较长,或发生概率比较高,请直接联系技术支持(联系方式: toddzhao@tencent.com)。
100030 用户未对应用进行授权,需要引导用户重新登录授权,并且在登录的Scope参数里,加上相应的API名称(请参考API列表)。

所有的API都必需经过QQ互联对应用授权),用户对应用授权后才可以调用。

100014 access_token过期,目前支持的access_token有效期为三个月,需要重新走登录流程,获取新的access_token。

后期也可以使用Refresh Token来获取新的access_token(该功能即将上线)

100015 access_token失效。要重新走登录流程,获取新的access_token。

产生该错误有两个原因:

1. 用户在QQ空间里取消了对应用的授权,会导致当前保存到应用里的AccessToken被废除掉。

2. 用户在不同的设备上进行了QQ登录,导致在原来设备上的保存的AccessToken被废除掉。

100016 access_token校验失败。建议先重新走登录流程来换取新的access_token,使用新的access_token仍然无法通过校验,请通过企业QQ联系技术支持(号码:800030681。直接在QQ的“查找联系人”中输入号码即可开始对话)。

更多返回码与错误信息的对照说明,请参考《公共返回码说明》文档。

6. FAQ

 

6.1 授权相关

应用调用OpenAPI时,需要哪些授权?

应用调用OpenAPI时,需要有相应的授权后才能调用,授权包括:

(1) 应用调用OpenAPI的授权。

有些OpenAPI仅对可信赖的合作应用开放,调用这些OpenAPI时需要提交申请以获得访问权限。需要申请授权的API信息,请参见《API列表》。

(2) 登录用户对应用的授权

如果应用调用接口是返回100030的错误信息,说明应用有该OpenAPI的调用权限,但并未申请用户授权。请重新引导该用户走登录授权流程,并在scope参数里加上需要用户进行授权的OpenAPI。如果无法确认有多少OpenAPI需要用户授权,可以直接在scope参数里填写"all"来表示需要用户授权所有OpenAPI。

6.2 Andriod_SDK_V1.5相关问题

 

6.2.1 只有java开发的应用可以使用本SDK吗?非原生开发的应用可以使用吗?

目前我们提供了Android的SDK,只有java开发的应用可以使用。

非原生开发的应用不可以使用本SDK(非原生开发应用:没有使用android sdk和java语言开发的应用,例如使用flash air技术开发的app,通过工具转换成android apk的应用)。

6.2.2 调用发送分享和应用分享有什么区别?

发送分享指的是V1.2版本的旧接口addShare,使用此接口不能@好友;V1.6新增的应用分享接口可以@好友。

6.3 如何获取Android app包名?

包名又称Package Name,是应用程序在android系统中的唯一ID标识,获取方法如下:

(1) 打开Eclipse,导入app 的工程,打开AndroidManifest.xml文件,展现如下:

android_sdk_1_4_pic_4.jpg

其中,Package选项后面的com.yourcompan.yourappname就是包名,不同的app,packagename是不一样的。

(2) 如果是通过文本形式打开的AndroidManifext.xml,展现如下:

android_sdk_1_4_pic_5.png

同样,package字段后面填写的值 com.yourcompan.yourappname 也是包名。

返回顶部