![]() |
TencentOpenAPI iOS SDK
v1.4 Beta
QQ互联开放平台 iOS SDK
|
【QQ登录】IOS SDK使用说明
QQ登录IOS SDK 封装了QQ登录的登录授权以及大部分OpenAPI,应用只需要修改相应参数,不需要理解验证授权流程,即可快速实现QQ登录功能。
IOS平台上(ipad,iphone,ipod)的应用,请在申请appid,appkey后,使用QQ互联提供的IOS SDK。
本SDK仅适用于移动应用,即基于【QQ登录】使用Implicit_Grant方式获取Access_Token接入的应用。
目录
1. IOS SDK下载
2. IOS SDK目录结构
4. 修改必要的代码
5. 调用SDK 登录
7. IOS SDK 安全登录
v1.3
新版SDK以framework形式发布
新增1个设置QQ头像接口(setUserHeadpic)
新增2个微博相关接口(matchNickTips,getIntimateFriends)
新增2个会员相关接口(getVipInfo,getVipRichInfo)
1.
IOS SDK 下载
请到【QQ登录】SDK下载页面下载最新版本QQ登录IOS SDK。
2.
IOS SDK目录结构
IOS
SDK 1.3 SDK包中带有两个文件。
1,TencentOpenAPI.framework打包了IOS SDK的头文件定义和具体实现。
2,TencentOpenApi_IOS_Bundle.bundle 打包了IOS SDK需要的资源文件。
1.
将IOS SDK中的TencentOpenAPI.framework和TencentOpenApi_IOS_Bundle.bundle文件拷贝到应用开发的目录下。
然后将TencentOpenAPI.framework从SDK的保存目录拖拽到工程导航视图(project navigator)中的Frameworks虚拟目录下。
2.在弹出的对话框中勾选“Create
groups for any added folders”,去掉“copy items
into destination group’s folder(if needed)”,在Add
to targets中选择要加入SDK的target之后点击finish。完成之后就将IOS SDK 1.3的framework文件加入了开发工程中。
3,
添加SDK依赖的系统库文件。分别是“libiconv.dylib”,“SystemConfiguration.framework”,“CoreGraphics.Framework”三个默认的库文件。
在Xcode中打开工程配置文件,选择“summary”一栏。
4.
在“summary”中选择“Linked
Frameworks and Libraries”一栏,点击“+”图标。
5.
直接在默认库文件中选择后点击“Add”,下方的图以添加“SystemConfiguration.framework”为例:
6.
返回后看到“SystemConfiguration.framework”已经在“Linked Frameworks and Libraries”中出现。
7.
在Xcode中打开工程配置文件,选择“Build Phases”一栏。
8.在“Build Phases”中选择展开“Copy Bundle Resources”一栏,并点击“+”图标
9.
选择“Add Other...”,进入IOS SDK文件所在目录,选择TencentOpenApi_IOS_Bundle.bundle,点击回车或者点击“Open”。
10.
返回后看到TencentOpenApi_IOS_Bundle.bundle已经在“Copy Bundle Resources”中出现。
11.
修改必要的工程配置属性。
在工程配置中的“Build Settings”一栏中找到“Linking”配置区,给“Other Linker Flags”配置项添加属性值“-ObjC”。
4.
修改必要的代码
1.
修改工程配置文件
在XCode中,选择你的工程设置项,选中“TARGETS”一栏,在“info”标签栏的“URL type”添加一条新的“URL scheme”,新的scheme = tencent + appid。如果您使用的是XCode3或者更低的版本,则需要在plist文件中添加。Demo中我们注册的appid是222222。如下图
2.
重写AppDelegate 的handleOpenURL和openURL方法
openURL:
- (BOOL)application:(UIApplication
*)application openURL:(NSURL *)url sourceApplication:(NSString
*)sourceApplication annotation:(id)annotation{
return [TencentOAuth HandleOpenURL:url];
}
handleOpenURL
- (BOOL)application:(UIApplication
*)application handleOpenURL:(NSURL *)url{
return [TencentOAuth HandleOpenURL:url];
}
3.
在代码中实现TencentSessionDelegate协议中的方法
具体协议可以参照TencentOpenAPI.framework /Headers中的TencentOAuth.h文件中
4. 初始化IOS SDK API数据对象TencentOAuth。
(1) 创建TencentOAuth并初始化其appid,demo为222222。delegate为实现TencentSessionDelegate的对象:
_tencentOAuth = [[TencentOAuth alloc] initWithAppId:@"222222", andDelegate:self];
(2) 初始化redirectURI(这里需要填写注册APP时填写的域名。默认可以不用填写。建议不用填写。demo中注册时的地址是“www.qq.com”):
_tencentOAuth.redirectURI =
@"www.qq.com";
(3)设置应用需要用户授权的API列表。
(建议如果授权过多的话,可能会造成用户不愿意授权。这里最好只授权应用需要用户赋予的授权。):
_permissions = [[NSArray
arrayWithObjects:@"get_user_info", @"add_share", nil]
retain];
1.登录时,调用TencetnOAuth对象的authorize方法:
[_tencentOAuth
authorize:_permissions inSafari:NO];
2.
登录完成后,会调用TencentSessionDelegate中关于登录的协议方法。
登录成功:
@protocol TencentSessionDelegate
<NSObject>
- (void)tencentDidLogin
{
_labelTitle.text = @"登录完成";
if
(_tencentOAuth.accessToken
&& 0 != [_tencentOAuth.accessToken length])
{
// 记录登录用户的OpenID、Token以及过期时间
_labelAccessToken.text = _tencentOAuth.accessToken;
}
else
{
_labelAccessToken.text = @"登录不成功
没有获取accesstoken";
}
}
非网络错误导致登录失败:
@protocol TencentSessionDelegate
<NSObject>
-(void)tencentDidNotLogin:(BOOL)cancelled
{
if (cancelled)
{
_labelTitle.text = @"用户取消登录";
}
else
{
_labelTitle.text
= @"登录失败";
}
}
网络错误导致登录失败:
@protocol TencentSessionDelegate
<NSObject>
-(void)tencentDidNotNetWork
{
_labelTitle.text=@"无网络连接,请设置网络";
}
3.
登录成功后,即可获取到access token和openid。accesstoken和 openid保存在TencentOAuth对象中。可以通过相应的属性方法直接获得。
[_tencentOAuth accessToken] ;
[_tencentOAuth openId] ;
1.由于登录是异步过程,这里可能会由于用户的行为导致整个登录的的流程无法正常走完,即有可能由于用户行为导致登录完成后不会有任何登录回调被调用。开发者在使用SDK进行开发的时候需要考虑到这点,防止由于一直在同步等待登录的回调而造成应用的卡死,建议在登录的时候将这个实现做成一个异步过程。
2.获取到的access token具有3个月有效期,过期后提示用户重新登录授权。
3.
第三方网站可存储access token信息,以便后续调用OpenAPI访问和修改用户信息时使用。如果需要保存授权信息,需要保存登录完成后返回的accessToken,openid 和 expirationDate三个数据,下次登录的时候直接将这三个数据是设置到TencentOAuth对象中即可。
获得:
[_tencentOAuth accessToken]
;
[_tencentOAuth openId] ;
[_tencentOAuth expirationDate] ;
设置:
[_tencentOAuth setAccessToken:accessToken] ;
[_tencentOAuth setOpenId:openId] ;
[_tencentOAuth setExpirationData:expirationDate] ;
4. 建议应用在用户登录后,即调用getUserInfo接口获得该用户的头像、昵称并显示在界面上,使用户体验统一。
SDK中具体支持的API种类和每条API的参数说明,请参照【QQ登录】API文档。这里用设置用户头像举例说明。
(1) OpenAPI参数字典封装
在封装各接口的参数字典时,推荐使用为每个接口新增的参数封装辅助类,如:
接口(BOOL)addShareWithParams:(NSMutableDictionary *)params
对应辅助类TCAddShareDic
TCAddShareDic辅助类中属性:
@property (nonatomic, retain) TCRequiredStr
paramTitle;
对应于CGI请求中参数"title"
TCRequiredStr 表示这是一个必填参数,类型是字符串
TCOptionalStr 表示这是一个可选参数,类型是字符串
(2) setUserHeadpic接口调用示例
设置QQ头像时,调用TencetnOAuth对象的setUserHeadpic方法:
TCSetUserHeadpic
*params = [TCSetUserHeadpic dictionary];
params.paramImage
= image;
params.paramFileName
= @"make";
[_tencentOAuth
setUserHeadpic:params]
设置头像完成后,会调用TencentSessionDelegate中的setUserHeadpicResponse返回调用结果:
@protocol
TencentSessionDelegate <NSObject>
-
(void)setUserHeadpicResponse:(APIResponse*) response
{
if (nil == response)
{
return;
}
if (URLREQUEST_FAILED ==
response.retCode
&& kOpenSDKErrorUserHeadPicLarge == response.detailRetCode)
{
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"操作失败" message:[NSString
stringWithFormat:@"您的图片大小超标啦,请更换一张试试呢:)"]
delegate:self
cancelButtonTitle:@"我知道啦" otherButtonTitles: nil];
[alert show];
[alert release];
}
}
(3) 返回数据说明
APIResponse属性:
retCode - 网络请求返回码,主要表示服务器是否成功返回数据
seq - 请求的序列号,依次递增,方便内部管理
errorMsg - 错误消息
jsonResponse - 由服务器返回的json格式字符串转换而来的json字典数据(具体参数字段请参见对应API说明文档)
message - 服务器返回的原始字符串数据
detailRetCode - 新增的详细错误码,以区分不同的错误原因(记得说明老版本(v1.2)SDK接口中这个新增的详细错误码还未启用,新增接口中这个参数才有意义)
(4) 返回码说明
retCode网络请求返回码说明:
0 表示成功,请求成功发送到服务器,并且服务器返回的数据格式正确
1 表示失败,可能原因有网络异常,或服务器返回的数据格式错误,无法解析
detailRetCode详细错误码说明:
kOpenSDKInvalid -无效的错误码
[公共错误码]
kOpenSDKErrorSuccess - 成功
kOpenSDKErrorUnknown - 未知错误
kOpenSDKErrorUserCancel - 用户取消
kOpenSDKErrorReLogin - token无效或用户未授权相应权限需要重新登录
kOpenSDKErrorOperationDeny - 第三方应用没有该api操作的权限
[网络相关错误码]
kOpenSDKErrorNetwork - 网络错误,网络不通或连接不到服务器
kOpenSDKErrorURL - URL格式或协议错误
kOpenSDKErrorDataParse - 数据解析错误,服务器返回的数据解析出错
kOpenSDKErrorParam - 传入参数错误
kOpenSDKErrorConnTimeout - http连接超时
kOpenSDKErrorSecurity - 安全问题
kOpenSDKErrorIO - 下载和文件IO错误
kOpenSDKErrorServer - 服务器端错误
[webview中特有错误]
kOpenSDKErrorWebPage - 页面错误
[设置头像 自定义错误码段]
kOpenSDKErrorUserHeadPicLarge - 图片过大 设置头像自定义错误码
7.
IOS SDK安全登录
IOS
SDK 1.3开始支持应用跳转到手机QZone IOS版本进行QQ登录。使用手机QZone进行登录的方式会给用户提供更加安全,快捷的体验
。这种方式仅仅需要用户安装最新版本的手机QZone,版本号为3.4.3或者更高版本。应用开发者不需要添加任何代码。
在没有安装手机QZone(3.4.3或更高)的情况下,SDK按原流程进行授权登录,跳转到登录页面。