Android_SDK使用说明


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


目录

1. Andriod_SDK_V1.6 简介

Android SDK以Jar包形式提供,封装了QQ登录的登录授权以及大部分OpenAPI,移动应用只需要修改少量代码,不需要理解验证授权流程,即可快速实现QQ登录功能,并可调用平台提供的OpenAPI。
Android平台上的应用,要使用QQ互联提供的Android SDK,请先在QQ互联开放平台进行注册,获取appid和appkey。
主要提供的功能接口有:登录、注销、邀请好友、应用分享、获取用户信息、获取用户相册列表、发送分享、发表说说、上传图片、创建相册、邀请好友、应用分享、设置QQ头像等功能,Andriod_SDK_V1.6新增了发送请求、赠送礼物、发送挑战、炫耀、增量授权、分享消息给QQ好友等功能,更多详细信息请查看API列表

2. 下载Android SDK

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

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

以下以eclipse为开发的IDE进行范例说明:
(1)创建一个工程,并把open-sdk.jar放到libs(或lib)目录下,如下图所示:
android_sdk_1_4_pic_1.png
(2)将open-sdk.jar加入编译路径中。 具体的操作步骤为:选中open-sdk.jar,右键菜单中选择Build Path, 选择Add to Build Path,如下图所示:
android_sdk_1_4_pic_2.png

在工程的Referenced Libraries目录下看到导入的jar包,说明已经成功将jar包加入build path,如下图所示:
android_sdk_1_4_pic_3.png

4. Andriod_SDK_V1.6 使用说明

在使用Andriod_SDK_V1.6时,主要有以下五个步骤:
Step1:给应用的AndroidManifest增加SDK需要的配置;
Step2:创建SDK的主要实现类的实例;
Step3:实现SDK接口回调;
Step4:access_token、openid的获取和使用;
Step5:调用OpenAPI。

4.1 配置AndroidManifest

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

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<application>
 <activity
       android:name="com.tencent.tauth.AuthActivity"
       android:noHistory="true"
       android:launchMode="singleTask" >
    <intent-filter>
           <action android:name="android.intent.action.VIEW" />
       	<category android:name="android.intent.category.DEFAULT" />
       	<category android:name="android.intent.category.BROWSABLE" />
           <data android:scheme="tencent你的AppId" />
    </intent-filter>
 </activity>
<application>

其中,如果你已经添加了"android.permission.INTERNET"和"android.permission.ACCESS_NETWORK_STATE"权限,则无需重复添加。
而"你的AppId"则要替换成具体应用的AppId,例如你的AppId是"222222",则<data>标签应该是这样的:

<data android:scheme="tencent222222" />



4.2 创建实例

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

@Override
public void onCreate(Bundle savedInstanceState){
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Tencent类是SDK的主要实现类,开发者可通过Tencent类访问腾讯开放的OpenAPI。
// 其中APP_ID是分配给第三方应用的appid,类型为String。
mTencent = Tencent.createInstance(APP_ID, this.getApplicationContext());
// 1.4版本:此处需新增参数,传入应用程序的全局context,可通过activity的getApplicationContext方法获取
// 初始化视图
initViews();
}


4.3 实现回调

所有的SDK接口调用,都会传入一个回调,用以接收SDK返回的调用结果。回调的主要接口有两种:
(1) IUiListener:调用SDK已经封装好的接口时,例如:登录、快速支付登录、应用分享、应用邀请等接口。
IUiListener的实现示例代码如下:

private class BaseUiListener implements IUiListener {
@Override
public void onComplete(JSONObject response) {
mBaseMessageText.setText("onComplete:");
mMessageText.setText(response.toString());
doComplete(response);
}
protected void doComplete(JSONObject values) {

}
@Override
public void onError(UiError e) {
showResult("onError:", "code:" + e.errorCode + ", msg:"
+ e.errorMessage + ", detail:" + e.errorDetail);
}
@Override
public void onCancel() {
showResult("onCancel", "");
}
}

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

private class BaseApiListener implements IRequestListener {
@Override
public void onComplete(final JSONObject response, Object state) {
showResult("IRequestListener.onComplete:", response.toString());
doComplete(response, state);
}
protected void doComplete(JSONObject response, Object state) {
}
@Override
public void onIOException(final IOException e, Object state) {
showResult("IRequestListener.onIOException:", e.getMessage());
}
@Override
public void onMalformedURLException(final MalformedURLException e,
Object state) {
showResult("IRequestListener.onMalformedURLException", e.toString());
}
@Override
public void onJSONException(final JSONException e, Object state) {
showResult("IRequestListener.onJSONException:", e.getMessage());
}
@Override
public void onConnectTimeoutException(ConnectTimeoutException arg0,
Object arg1) {
// TODO Auto-generated method stub
}
@Override
public void onSocketTimeoutException(SocketTimeoutException arg0,
Object arg1) {
// TODO Auto-generated method stub
}
//1.4版本中IRequestListener 新增两个异常
@Override
public void onNetworkUnavailableException(NetworkUnavailableException e, Object state){
// 当前网络不可用时触发此异常
}
@Override
public void onHttpStatusException(HttpStatusException e, Object state) {
// http请求返回码非200时触发此异常
}
public void onUnknowException(Exception e, Object state) {
// 出现未知错误时会触发此异常
}
}


应用在调用SDK提供的接口时,将实现了对应回调接口的实例传入。当SDK的接口调用完成后,具体如登录、应用邀请和应用分享调用完成后,会回调传入的接口实例。
特别注意
应用调用Andriod_SDK_V1.6接口时,如果要成功接收到回调,需要在调用接口的Activity的onActivityResult方法中增加如下代码:

@Override

 protected void onActivityResult(int requestCode, int resultCode, Intent data) {
       mTencent.onActivityResult(requestCode, resultCode, data) ;
 }


4.4 access_token、openid的获取和使用

4.4.1获取access_token和openid

应用通过调用SDK的登录接口获取access_token和openid。登录接口的调用说明详见SDK包里的《Andriod_SDK_V1.6接口调用说明》中的"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参数在存储前需进行如下计算:

System.currentTimeMillis() + Long.parseLong(expires_in) * 1000;

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

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

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

String openid = "1234567896ASDFGHJKLLIUYT";
String access_token = "2C0884DC4B930010D852D8D504FC9F4D";
String expires_in = "7776000"; // 实际值需要通过上面介绍的方法来计算
mTencent = Tencent.createInstance(APP_ID);
mTencent.setOpenId(openid);
mTencent.setAccessToken(access_token, expires_in);


4.5 调用OpenAPI

SDK中Tencent类是对外提供功能接口的主要实现类,所有接口都通过Tencent类的实例来调用。
接口的详细调用说明,请参见SDK包中的《Andriod_SDK_V1.6接口调用说明》。
接口调用的详细示例,请参见SDK包中的sample\src\com\tencent\sample目录下的MainActivity.java文件。

4.6 混淆说明

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

-keep class com.tencent.open.TDialog$*
-keep class com.tencent.open.TDialog$* {*;}
-keep class com.tencent.open.PKDialog
-keep class com.tencent.open.PKDialog {*;}
-keep class com.tencent.open.PKDialog$*
-keep class com.tencent.open.PKDialog$* {*;}


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 也是包名。

以上信息是否解决您的问题?

Copyright © 1998 - 2021 Tencent. All Rights Reserved.

腾讯公司 版权所有

返回顶部