Android_SDK使用说明

目录

What's New?

2015年10月30日,Android SDK V2.9.4版本正式发布。

1. Andriod_SDK简介

Android SDK以Jar包形式提供,封装了QQ登录的登录授权以及大部分OpenAPI及社交渠道的分享、邀请、请求礼物、挑战炫耀、语音、应用评价、好友召回、获取附近的人API,移动应用只需要修改少量代码,即可快速实现QQ登录功能,并可调用平台 提供的OpenAPI及社交渠道API的功能。
主要提供的功能接口有:登录、注销、邀请好友、应用分享、获取用户信息、获取用户相册列表、发送分享、发表说说、上传图片、创建相册、设置QQ头像、增量授权、分享消息给QQ好友、发送带图微博发送请求、赠送礼物、发送挑战、炫耀等功能,Andriod_SDK_V2.1新增了好友召回,获取附近也在玩该应用的人等新功能。具体修改可参考《接口调用说明》文档。

2.下载Android SDK

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

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

以下以eclipse为开发的IDE进行范例说明:
使用Eclipse ADT 17 以上版本开发者
请在工程目录下新建一个文件夹libs,将open-sdk.jar文件和mta_sdk_x.x.x.jar文件拷贝到这个文件下(mta包请自主选择,非必须,mta详细说明见sdk开发包mta文档),然后在Eclipse里面刷新工程即可完成SDK文件的引入。
使用Eclipse ADT 17 以下版本开发者
请参考下面的步骤引入SDK文件:
(1)创建一个工程,并把open-sdk.jar文件和mta_sdk_x.x.x.jar文件拷贝到libs(或lib)目录下,如下图所示:
android_sdk_1.png
(2)将open-sdk.jar加入编译路径中。
选中open-sdk.jar,右键菜单中选择Build Path, 选择Add to Build Path,如下图所示:
android_sdk_2.png
(3)将mta_sdk_x.x.x.jar加入编译路径中。
按照上面的方法,将mta_sdk_x.x.x.jar加入编译路径中。
在工程的Referenced Libraries目录下看到导入的jar包,说明已经成功将jar包加入build path,如下图所示:
android_sdk_3.png

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);

<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(Object response) {

     //V2.0版本,参数类型由JSONObject 改成了Object,具体类型参考api文档

mBaseMessageText.setText("onComplete:");
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的接口调用完成后,具体如登录、应用邀请和应用分享调用完成后,会回调传入的接口实例。
特别注意
在某些低端机上调用登录后,由于内存紧张导致APP被系统回收,登录成功后无法成功回传数据。解决办法如下
在调用login的Activity或者Fragment重写onActivityResult方法,示例代码如下:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if(requestCode == Constants.REQUEST_API) {
	if(resultCode == Constants.RESULT_LOGIN) {
	    mTencent.handleLoginData(data, loginListener);
	}
    }
    super.onActivityResult(requestCode, resultCode, data);
}


SDK_V2.0引入了AssistActivity,开发者只需在androidManifest.xml中注册即可。代码如下:

 <activity android:name="com.tencent.connect.common.AssistActivity"
           android:theme="@android:style/Theme.Translucent.NoTitleBar"
           android:configChanges="orientation|keyboardHidden|screenSize" 
/>

}


4.4 access_token、openid的获取和使用

4.4.1获取access_token和openid

应用通过调用SDK的登录接口获取access_token和openid。登录接口的调用说明详见SDK包里的《Andriod_SDK_V2.0接口调用说明》中的"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_V2.0接口调用说明》。
接口调用的详细示例,请参见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$* {*;}


4.7 签名验证说明

为了防止开发商所申请的appid被非法利用,也为了防止应用安装包被恶意修改,我们在SDK1.7中,增加了应用签名验证的功能,具体使用步骤如下:
(1)分别使用debug版keystore和release版keystore签名打包自己的应用,生成两个apk包。
(2)通过签名工具分别获取这两个apk包的签名值,(签名工具在tools目录下)。
(3)在腾讯开放平台的注册流程中,分别填入debug版的签名值和release版的签名值。
(4)一旦使用该功能,则不能再随意更换keystore文件,否则会被认为是apk包被修改了,导致登录授权验证不通过。
特别注意:
该功能不强制使用,但为了安全起见,我们建议使用。只有拥有合法签名的应用程序才能够进入登录授权界面,所以应用要确保自己在接入平台上填入的签名值与实际应用程序的签名值一致。

5. 返回码说明

详见公共返回码说明

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相关问题

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

目前我们提供了Android的SDK,没有单独开发针对其他非原生开发的应用的SDK。
但非原生开发的应用也可以使用本SDK,只需要创建一个Android的Activity组建用于创建实例和接收回调。 (非原生开发应用指:没有使用Android SDK和java语言开发的应用,例如使用flash air技术开发,通过工具转换成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 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部