Android SDK说明文档

跳转到: 导航, 搜索

目录

概述

微博Android平台SDK为第三方微博应用提供了文档易用的微博API调用服务,使第三方客户端无需了解复杂的验证,API调用过程。并可以实现分享到微博的功能,可以分享文字,或者多媒体信息到内置的分享页面,并发送到微博。

名词解释

Consumer_key 分配给每个第三方应用的App key。用于鉴权身份,显示来源等功能。
Consumer_secret 生成请求Request Token的secret,与Consumer key一起分配。
OAuth_token 服务器根据App key和时间,Callback_url等哈希出的Token值,用于获取OAuth Verifier。
Oauth_token_secret 与OAuth Token一起使用,用于获取OAuth Verifier。
OAuth_verifier 通过OAuth页面返回的verifier,用于最终获取Access Token。
Access_token 表示用户身份的Token,用于微博API的调用。

整体架构

主要类说明:

andr1.jpg


  • 1、Weibo: 微博API 接口类,对外提供Weibo API的调用,包括登录,API调用,微博分享等功能。
  • 2、AsyncWeiboRunner:微博API异步执行类,封装了回调接口,通过创建线程来调用Weibo中的接口方法。
  • 3、Utility:互联网工具类,包括接口请求GET/POST封装,BASE64等encode,decode方法。
  • 4、WeiboException:微博异常封装类,封装了微博的各个异常。

接口说明

Class com.weibo.net.Weibo:

获取Request Token

接口名称:public RequestToken getRequestToken(Context context, String key, String secret, String callback_url);


参数名称 作用
Context 传递应用上下文环境,用于获取当前网络状态,弹出对话框等。
Key 分配给第三方客户端的App key
Secret 分配给第三方客户端的App secret
Callback_url 用于OAuth authorize页面回调的url


返回结果:RequestToken:RequestToken封装Request Tokens属性类,继承自Token,包含有OAuth_token,OAuth_token_secret多个属性。

获取Access Token

接口名称:public AccessToken generateAcessToken(Context context, RequestToken requestToken)

参数名称 作用
Context 传递应用上下文环境,用于获取当前网络状态,弹出对话框等。
RequestToken 用于存取OAuth Token和OAuth Secret的Token类

返回结果:AccessToken: AccessToken封装Access Tokens属性类,继承自Token,包含Access_token, OAuth_token_secret多个属性。

获取OAuth2.0 的Access Token

接口名称:OAuth2AccessToken getOauth2AccessToken(Context context, String app_key,String app_secret, String usrname, String password)

参数名称 作用
Context 传递应用上下文环境,用于获取当前网络状态,弹出对话框等。
App_key Client_id,第三方应用的APPkey
App_secret Client_secret,第三方应用的APPsecret
Username 微博用户名称
Password 微博用户密码

返回结果:OAuth2AccessToken: OAuth2AccessToken封装Tokens属性类,继承自Token,包含Access_token, OAuth_token_secret多个属性。

微博API请求

接口名称:public String request(Context context, String url, WeiboParameters params, String httpMethod)

参数名称 作用
Context 传递应用上下文环境,用于获取当前网络状态,弹出对话框等。
Params 封装每个微博API请求的参数对到实体类WeiboParameters中
HttpMthod API请求方式 (“GET”, “POST”, “DELETE”)

返回结果:String:返回所请求的服务器所返回的xml/json数据。

分享到微博

接口名称:public boolean share2weibo(Activity activity, String accessToken, String tokenSecret, String content, String picPath)

参数名称 作用
Activity Activity引用,用于调起新的分享activity或者分享dialog。
AccessToken 代表用户身份的Access Token。
TokenSecret OAuth_token_secret,用户获取AcessToken,鉴权用户身份等。
Content 要分享的微博内容,限140个字。
PicPath 分享到微博的图片路径(图片大小<1M)

返回结果:Boolean: true分享成功,false 分享失败。

通过xAuth认证获取用户身份

接口名称:public AccessToken getXauthAccessToken(Context context, String app_key, String app_secret, String usrname, String password)

参数名称 作用
Context 传递应用上下文环境,用于获取当前网络状态,弹出对话框等。
App_key 分配给第三方客户端的Consumer key。
App_secret 分配给第三方客户端的Consumer secret。
Username 微博用户名称
Password 微博用户密码

返回结果:AccessToken: AccessToken封装Access Tokens属性类,继承自Token,包含Access_token, OAuth_token_secret多个属性。

通过OAuth2.0隐式授权认获取AccessToken

接口名称:void authorize(Activity activity, final WeiboDialogListener listener)

参数名称 作用
Activity 传递应用上下文环境,用于获取当前网络状态,弹出对话框等。
Listener 授权对话框回调接口。处理授权完成、授权失败、授权取消等事件。

实例分析

以下代码的具体信息请参考com_weibo_android_example工程。

svn地址为:http://weibo-android-sdk.googlecode.com/svn/example

登录

第一步In AuthorizeActivity: 获取微博实体类,传入App key, secret,以及callback_url。

Weibo weibo = Weibo.getInstance();
RequestToken requestToken = weibo.getRequestToken(AuthorizeActivity.this, Weibo.getAppKey(), Weibo.getAppSecret(), AuthorizeActivity.URL_ACTIVITY_CALLBACK);


第二步In AuthorizeActivity: 用获取到的OAuth Token , OAuth_token_secret访问Open API authorize页面。

Uri uri = Uri.parse(AuthorizeActivity.URL_ACTIVITY_CALLBACK);
startActivity(new Intent(Intent.ACTION_VIEW, uri));


第三步 In TestActivity: 获取到Callback的OAuth_verifier,并根据它获取AccessToken,完成登录。

public void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
    this.setContentView(R.layout.timeline);
	Uri uri = this.getIntent().getData();
    String oauth_verifier = uri.getQueryParameter("oauth_verifier");
    mWeibo.addOauthverifier(oauth_verifier);
    try {
    	mWeibo.generateAccessToken(this, null);

访问微博API

第一步 In TestActivity: 调用Weibo实体类中Request进行简单的微博API访问,前提是AccessToken已经获取到。

private String getPublicTimeline(Weibo weibo) throws MalformedURLException, IOException, WeiboException {
	String url = Weibo.SERVER + "statuses/public_timeline.json";
    WeiboParameters bundle = new WeiboParameters();
    bundle.add("source", Weibo.getAppKey());
    String rlt = weibo.request(this, url, bundle, "GET", mWeibo.getAccessToken());
    return rlt;
}

分享到微博

第一步 In TestActivity: 得到Weibo实体类,传入我们需要分享的文字”abc”, 以及要分享的图片路径”picPath”。

File file = Environment.getExternalStorageDirectory();
String sdPath = file.getAbsolutePath();
// 请保证SD卡根目录下有这张图片文件
String picPath = sdPath + "/" + "abc.jpg";
File picFile = new File(picPath);
if (!picFile.exists()) {
	Toast.makeText(TestActivity.this, "图片" + picPath + "不存在!", Toast.LENGTH_SHORT).show();
	picPath = null;
}
try {
    share2weibo("abc", picPath);


第二步 In TestActivity: 调用微博中Share2Weibo方法,传入Activity引用,调起我们的分享页面。

private void share2weibo(String content, String picPath) throws WeiboException {
	Weibo weibo = Weibo.getInstance();
    weibo.share2weibo(this, weibo.getAccessToken().getToken(), weibo.getAccessToken().getSecret(), content, picPath);
}

异步调用AsyncWeiboRunner中API方法

第一步In ShareActvity:

调用类实现一部回调RequestLisener接口。
public class ShareActivity extends Activity implements OnClickListener, RequestListener {

第二步In ShareActvity: 调用异步upload接口,实现发微博功能。

private String upload(Weibo weibo, String source, String file, String status, String lon, String lat) throws WeiboException {
	WeiboParameters bundle = new WeiboParameters();
    bundle.add("source", source);
    bundle.add("pic", file);
    bundle.add("status", status);
    if (!TextUtils.isEmpty(lon)) {
	    bundle.add("lon", lon);
    }
    if (!TextUtils.isEmpty(lat)) {
	    bundle.add("lat", lat);
    }
    String rlt = "";
    String url = Weibo.SERVER + "statuses/upload.json";
    AsyncWeiboRunner weiboRunner = new AsyncWeiboRunner(weibo);
    weiboRunner.request(this, url, bundle, Utility.HTTPMETHOD_POST, this);

	return rlt;
}


第三步In ShareActvity: 实现回调,对发表成功onComplete,以及发表失败onError的情况进行处理。

@Override
public void onComplete(String response) {
	runOnUiThread(new Runnable() {
	@Override
	public void run() {
	Toast.makeText(ShareActivity.this, R.string.send_sucess, Toast.LENGTH_LONG).show();
	}
	});
	this.finish();
}

@Override
public void onIOException(IOException e) {
	// TODO Auto-generated method stub
}

@Override
public void onError(final WeiboException e) {
	runOnUiThread(new Runnable() {
	@Override
    public void run() {
    	Toast.makeText(
        	ShareActivity.this,
            String.format(ShareActivity.this.getString(R.string.send_failed) + ":%s", e.getMessage()), Toast.LENGTH_LONG).show();
        }
    });
}

通过Oauth2.0隐式授权获得AccessToken

第一步 In AuthorizeActivity: 调用setRedirectUrl方法设置应用回调页。

Weibo weibo = Weibo.getInstance();
// !!Don't forget to set app_key and secret before get token!!!
weibo.setupConsumerConfig(CONSUMER_KEY, CONSUMER_SECRET);
// Oauth2.0 隐式授权认证方式
weibo.setRedirectUrl("http://www.sina.com");
weibo.authorize(AuthorizeActivity.this, new AuthDialogListener());

对于Mobile客户端应用来说,是不存在Server的,故此处的应用回调页地址只要与新浪微博开放平台->我的应用->应用信息->高级应用->授权设置->应用回调页中的url地址保持一致就可以了,如图所示:

andr3.jpg

第二步In AuthorizeActivity: 实现WeiboDialogListener接口。授权成功后可在onComplete函数中获得accesstoken信息。具体如何保存、使用accesstoken信息由开发者自行处理。

class AuthDialogListener implements WeiboDialogListener {

        @Override
        public void onComplete(Bundle values) {
            String token = values.getString("access_token");
            String expires_in = values.getString("expires_in");
            mToken.setText("access_token : " + token + "  expires_in: " + expires_in);
            AccessToken accessToken = new AccessToken(token, CONSUMER_SECRET);
            accessToken.setExpiresIn(expires_in);
            Weibo.getInstance().setAccessToken(accessToken);
            Intent intent = new Intent();
            intent.setClass(AuthorizeActivity.this, TestActivity.class);
            startActivity(intent);
        }

        @Override
        public void onError(DialogError e) {
            Toast.makeText(getApplicationContext(), "Auth error : " + e.getMessage(),
                    Toast.LENGTH_LONG).show();
        }

        @Override
        public void onCancel() {
            Toast.makeText(getApplicationContext(), "Auth cancel", Toast.LENGTH_LONG).show();
        }

        @Override
        public void onWeiboException(WeiboException e) {
            Toast.makeText(getApplicationContext(), "Auth exception : " + e.getMessage(),
                    Toast.LENGTH_LONG).show();
        }

    }



第三步 In AuthorizeActivity:

调用authorize方法,弹出授权对话框,进行授权。授权成功后即可获得accestoken。
// !!Don't forget to set app_key and secret before get token!!!
weibo.setupConsumerConfig(CONSUMER_KEY, CONSUMER_SECRET);
// Oauth2.0 隐式授权认证方式
weibo.setRedirectUrl("http://www.sina.com");
weibo.authorize(AuthorizeActivity.this, new AuthDialogListener());


andr5.png

SDK使用说明

  • 1、将SDK的工程项目导入到eclipse中
  • 在eclipse中选择File->Import->General->Existing Projects into Workspace。
  • 注意:SDK工程的编码格式为UTF-8。
  • 如图所示:[1]
  • 2、在需要集成本SDK的工程项目中添加Library
  • 右键 -> Properties -> Android。设置Library属性
  • 如图所示: [2]
  • 3、Manifest文件中必须包含以下permission:
  • <uses-permission android:name="android.permission.INTERNET"></uses-permission>
  • <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"></uses-permission>
  • <uses-permission android:name="android.permission.WRITE_APN_SETTINGS"></uses-permission>
  • <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"></uses-permission>
  • 4、代码中将APP_KEY, APP_SECRET存放在Weibo类中,可以修改成其他传参方式设置
  • In Weibo
private static String APP_KEY = "";
private static String APP_SECRET = "";


  • In TestActivity
Weibo.getAppKey();
Weibo.getAppSecret();
  • 5、SDK使用及修改必须遵守微博开发者协议,以及开源软件协议。