TencentOpenAPI iOS SDK  v1.4
QQ互联开放平台 iOS SDK
 全部  文件 函数 变量 类型定义 枚举 枚举值 属性 
TencentOpenAPI iOS SDK v1.4 文档说明

QQ登录】iOS SDK使用说明

QQiOS SDK 封装了QQ的登以及大部分OpenAPI用只需要修改相参数,不需要理解验证流程,即可快速实现QQ功能。

iOS平台上(ipadiphoneipod)的用,appidappkey后,使用QQ提供的iOS SDK

SDK适用于移动应,即基于【QQ】使用Implicit_Grant方式取Access_Token接入的用。 

目录

变更历史

1. iOS SDK下载

2. iOS SDK目录结构

3. 将iOS SDK文件添加到工程中

4. 修改必要的代码

5. 调用SDK 登录

6. 调用SDK 中的OpenAPI

7. iOS SDK 安全登录

 

变更历史

v1.4      新增SendStory空间分享接口(sendStory:friendList:

新增增量授权机

v1.3      新版SDKframework形式发布

新增1个设置QQ头像接口(setUserHeadpic

新增2个微博相关接口(matchNickTipsgetIntimateFriends

新增2个会员相关接口(getVipInfogetVipRichInfo

 

1. iOS SDK

【QQ】SDK面下载最新版本QQiOS SDK

2. iOS SDK目录结构

iOS SDK包中有两个文件:

1TencentOpenAPI.framework打包了iOS SDK头文件定义和具体实现。

2TencentOpenApi_iOS_Bundle.bundle 打包了iOS SDK需要的源文件。

3. iOS SDK文件添加到工程中

1. iOS SDK中的TencentOpenAPI.frameworkTencentOpenApi_IOS_Bundle.bundle文件拷贝到应用开发的目录下。

然后将TencentOpenAPI.frameworkSDK的保存目录拖拽到工程导航视图(project navigator)中的Frameworks虚拟目录下。

 

2.在弹出的对话框中勾选“Create groups for any added folders”,去掉“copy items into destination group’s folderif needed”,在Add to targets中选择要加入SDKtarget之后点击finish。完成之后就将iOS SDKframework文件加入了开发工程中。

 

3, 添加SDK依赖的系统库文件。分别是“libiconv.dylib”,“SystemConfiguration.framework”,“CoreGraphics.Framework”、“libsqlite3.dylib”、“CoreTelephony.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”配置项添加属性值“-fobjc-arc”。

 

4. 修改必要的代码

1. 修改工程配置文件

XCode中,选择你的工程设置项,选中“TARGETS”一栏,在“info”标签栏的“URL type”添加一条新的“URL scheme”,新的scheme = tencent + appid。如果您使用的是XCode3或者更低的版本,则需要在plist文件中添加。Demo中我们注册的appid222222。如下图

 

2. 重写AppDelegate handleOpenURLopenURL方法

 

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并初始化其appiddemo222222delegate为实现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];

 

5. 调用SDK登录

1.录时调用TencetnOAuth对象的authorize方法

[_tencentOAuth authorize:_permissions inSafari:NO]

 

2. 完成后,会调用TencentSessionDelegate中关于登录的协议方法。
成功:

 @protocol TencentSessionDelegate <NSObject>

- (void)tencentDidLogin

{

    _labelTitle.text = @"登录完成";

   

    if (_tencentOAuth.accessToken

        && 0 != [_tencentOAuth.accessToken length])

{

    //  记录登录用户的OpenIDToken以及过期时间

        _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 tokenopenidaccesstoken openid保存在TencentOAuth对象中。可以通过相应的属性方法直接获得。

[_tencentOAuth accessToken] ;

[_tencentOAuth openId] ;

提示: 

1.由于登录是异步过程,这里可能会由于用户的行为导致整个登录的的流程无法正常走完,即有可能由于用户行为导致登录完成后不会有任何登录回调被调用。开发者在使用SDK进行开发的时候需要考虑到这点,防止由于一直在同步等待登录的回调而造成应用的卡死,建议在登录的时候将这个实现做成一个异步过程。
2.取到的access token具有3个月有效期,期后提示用重新登录授

3. 第三方网站可存access token信息,以便后续调OpenAPI访问和修改用信息使用。如果需要保存授权信息,需要保存登录完成后返回的accessTokenopenid expirationDate三个数据,下次登录的时候直接将这三个数据是设置到TencentOAuth对象中即可。

获得:

[_tencentOAuth accessToken] ;

[_tencentOAuth openId] ;

[_tencentOAuth expirationDate] ;

设置:

[_tencentOAuth setAccessToken:accessToken] ;

[_tencentOAuth setOpenId:openId] ;

[_tencentOAuth setExpirationData:expirationDate] ;


4. 应用在用后,即getUserInfo接口像、昵称并示在界面上,使用验统一。

 

6. 调用SDK中的OpenAPI

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)  SendStory接口调用示例

注意:SendStory需在管理后台开通权限方可调用:

a)     以下信息必须在管理后台录入完整,且通过应用审核,状态为“已上线”,才会有使用sendstory的权限,否则会返回错误。

b)     为了保证分享出来的feeds可以实现应用的呼起和下载,请开发者一定对包名类名iphone schemeapk下载地址iphone appstore id 的准确性做检查。

 

发送空间定向分享时,调用TencetnOAuth对象的sendStory:friendList:方法

TCSendStoryDic *sendStoryDict = [TCSendStoryDic dictionary];

sendStoryDict.paramTitle = @"Share Title";

sendStoryDict.paramSummary = @"Share Summary";

sendStoryDict.paramDescription = @"Share Description";

sendStoryDict.paramPics = @"http://aaa.bbb/ccc.png";

sendStoryDict.paramShareUrl = @"http://xxx.yyy/zzz";

 

NSArray *fopenIdArray = @[@"ABCD1234ABCD1234ABCD1234ABCD1234", @"ABCD5678ABCD5678ABCD5678ABCD5678"];

 

[_tencentOAuth sendStory:sendStoryDict friendList:fopenIdArray];

 

空间定向分享发送完成后,会调用TencentSessionDelegate中的sendStoryResponse返回调用结果:

@protocol TencentSessionDelegate <NSObject>

- (void)sendStoryResponse:(APIResponse *)response

{

if (URLREQUEST_SUCCEED == response.retCode

&& kOpenSDKErrorSuccess == response.detailRetCode)

{

NSMutableString *str=[NSMutableString stringWithFormat:@""];

for (id key in response.jsonResponse) {

[str appendString: [NSString stringWithFormat:@"%@:%@\n",key,[response.jsonResponse objectForKey:key]]];

}

UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"操作成功"

message:[[NSString stringWithFormat:@"%@",str] decodeUnicode]

delegate:self

cancelButtonTitle:@"我知道啦"

otherButtonTitles: nil];

[alert show];

[alert release];

}

else

{

NSString *errMsg = [NSString stringWithFormat:@"errorMsg:%@\n%@", response.errorMsg, [response.jsonResponse objectForKey:@"msg"]];

UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"操作失败"

message:errMsg

delegate:self

cancelButtonTitle:@"我知道啦"

otherButtonTitles: nil];

[alert show];

[alert release];

}

}

 

(4)  使用增量授权

当第三方应用调用某个API接口时,如果服务器返回操作未被授权,则会触发增量授权逻辑。第三方应用需自行实现tencentNeedPerformIncrAuth:withPermissions:协议接口才能够进入增量授权逻辑,否则默认第三方应用放弃增量授权。示例如下:

- (BOOL)tencentNeedPerformIncrAuth:(TencentOAuth *)tencentOAuth

withPermissions:(NSArray *)permissions

{

// incrAuthWithPermissions是增量授权时需要调用的登录接口

// permissions是需要增量授权的权限列表

[tencentOAuth incrAuthWithPermissions:permissions];

return NO;    // 返回NO表明不需要再回传未授权API接口的原始请求结果;

// 否则可以返回YES

}

 

注意:在用户通过增量授权页重新授权登录后,第三方应用需更新自己维护的token及有效期限等信息。

**用户在增量授权时是可以更换帐号进行登录的,强烈要求第三方应用核对增量授权后的用户openid是否一致,以添加必要的处理逻辑(用户帐号变更需重新拉取用户的资料等信息)**

增量授权成功时,会通过tencentDidUpdate:协议接口通知第三方应用:

- (void)tencentDidUpdate:(TencentOAuth *)tencentOAuth

{

_labelTitle.text = @"增量授权完成";

   

    if (tencentOAuth.accessToken

        && 0 != [tencentOAuth.accessToken length])

{  // 在这里第三方应用需要更新自己维护的token及有效期限等信息

  // **务必在这里检查用户的openid是否有变更,变更需重新拉取用户的资料等信息**

        _labelAccessToken.text = tencentOAuth.accessToken;

    }

    else

    {

        _labelAccessToken.text = @"增量授权不成功,没有获取accesstoken";

    }

}

 

增量授权失败时,会通过tencentFailedUpdate:协议接口通知第三方应用:

- (void)tencentFailedUpdate:(UpdateFailType)reason

{

    switch (reason)

    {

        case kUpdateFailNetwork:

        {

            _labelTitle.text=@"增量授权失败,无网络连接,请设置网络";

            break;

        }

        case kUpdateFailUserCancel:

        {

            _labelTitle.text=@"增量授权失败,用户取消授权";

            break;

        }

        case kUpdateFailUnknown:

        default:

        {

            _labelTitle.text=@"增量授权失败,未知错误";

            break;

        }

    }

}

 

(5)  返回数据说明

APIResponse属性:

retCode - 网络请求返回码,主要表示服务器是否成功返回数据

seq - 请求的序列号,依次递增,方便内部管理

errorMsg - 错误消息

jsonResponse - 由服务器返回的json格式字符串转换而来的json字典数据(具体参数字段请参见对应API说明文档)

message - 服务器返回的原始字符串数据

detailRetCode - 新增的详细错误码,以区分不同的错误原因(记得说明老版本(v1.2)SDK接口中这个新增的详细错误码还未启用,新增接口中这个参数才有意义)

 

(6)  返回码说明

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.4支持应用跳转到手机QZone  iOS版本进行QQ登录。使用手机QZone进行登录的方式会给用户提供更加安全,快捷的体验 。这种方式仅仅需要用户安装最新版本的手机QZone,版本号为3.5或者更高版本。应用开发者不需要添加任何代码。

在没有安装手机QZone3.5或更高)的情况下,SDK按原流程进行授权登录,跳转到登录页面。