android api 怎么使用方法,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)目录下，如下图所示：

(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增加配置的节点下增加以下配置(注：不配置将会导致无法调用API)；

android:name="com.tencent.tauth.AuthActivity"

android:noHistory="true"

android:launchMode="singleTask" >

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

而"你的AppId"则要替换成具体应用的AppId，例如你的AppId是"222222"，则标签应该是这样的：

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接口时，如果要成功接收到回调，需要在调用接口的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.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参数在存储前需进行如下计算：

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.8接口调用说明》。

接口调用的详细示例，请参见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文件，展现如下：

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

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

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