lpw
2021-02-02 eec5d6105e17dfbe6335947986cecc93c9f30c29
commit | author | age
eec5d6 1 ///
L 2 /// \file TencentOAuth.h
3 /// \brief QQ互联开放平台授权登录及相关开放接口实现类
4 ///
5 /// Created by Tencent on 12-12-21.
6 /// Copyright (c) 2012年 Tencent. All rights reserved.
7 ///
8
9 #import <UIKit/UIKit.h>
10 #import "sdkdef.h"
11
12 @protocol TencentSessionDelegate;
13 @protocol TencentLoginDelegate;
14 @protocol TencentApiInterfaceDelegate;
15 @protocol TencentWebViewDelegate;
16
17 @class TencentApiReq;
18 @class TencentApiResp;
19
20 typedef NS_ENUM(NSUInteger, TencentAuthorizeState) {
21     kTencentNotAuthorizeState,
22     kTencentSSOAuthorizeState,
23     kTencentWebviewAuthorzieState,
24 };
25
26 typedef NS_ENUM(NSUInteger, TencentAuthMode) {
27     kAuthModeClientSideToken,
28     kAuthModeServerSideCode,
29 };
30
31 #pragma mark - TencentOAuth(授权登录及相关开放接口调用)
32
33 /**
34  * \brief TencentOpenAPI授权登录及相关开放接口调用
35  *
36  * TencentOAuth实现授权登录逻辑以及相关开放接口的请求调用
37  */
38 @interface TencentOAuth : NSObject
39 {
40     NSMutableDictionary* _apiRequests;
41     NSString* _accessToken;
42     NSDate* _expirationDate;
43     id<TencentSessionDelegate> _sessionDelegate;
44     NSString* _localAppId;
45     NSString* _openId;
46     NSString* _redirectURI;
47     NSArray* _permissions;
48 }
49
50 /** Access Token凭证,用于后续访问各开放接口 */
51 @property(nonatomic, copy) NSString* accessToken;
52
53 /** Access Token的失效期 */
54 @property(nonatomic, copy) NSDate* expirationDate;
55
56 /** 已实现的开放接口的回调委托对象 */
57 @property(nonatomic, assign) id<TencentSessionDelegate> sessionDelegate;
58
59 /** 第三方应用在开发过程中设置的URLSchema,用于浏览器登录后后跳到第三方应用 */
60 @property(nonatomic, copy) NSString* localAppId;
61
62 /** 用户授权登录后对该用户的唯一标识 */
63 @property(nonatomic, copy) NSString* openId;
64
65 /** 用户登录成功过后的跳转页面地址 */
66 @property(nonatomic, copy) NSString* redirectURI;
67
68 /** 第三方应用在互联开放平台申请的appID */
69 @property(nonatomic, retain) NSString* appId;
70
71 /** 第三方应用在互联开放平台注册的UniversalLink */
72 @property(nonatomic, retain) NSString* universalLink;
73
74 /** 主要是互娱的游戏设置uin */
75 @property(nonatomic, retain) NSString* uin;
76
77 /** 主要是互娱的游戏设置鉴定票据 */
78 @property(nonatomic, retain) NSString* skey;
79
80 /** 登陆透传的数据 */
81 @property(nonatomic, copy) NSDictionary* passData;
82
83 /** 授权方式(Client Side Token或者Server Side Code) */
84 @property(nonatomic, assign) TencentAuthMode authMode;
85
86 /** union id */
87 @property(nonatomic, retain) NSString* unionid;
88
89 /** 第三方在授权登录/分享 时选择 QQ,还是TIM 。在授权前一定要指定其中一个类型*/
90 @property(nonatomic, assign) TencentAuthShareType authShareType;
91
92 /**
93  * 获取上次登录得到的token
94  *
95  **/
96 - (NSString *)getCachedToken;
97
98 /**
99  * 获取上次登录得到的openid
100  *
101  **/
102 - (NSString *)getCachedOpenID;
103
104 /**
105  * 获取上次登录的token过期日期
106  *
107  **/
108 - (NSDate *)getCachedExpirationDate;
109
110 /**
111  * 上次登录的token是否过期(本地判断)
112  **/
113 - (BOOL)isCachedTokenValid;
114
115 /**
116  * 删除上次登录登录的token信息
117  *
118  **/
119 - (BOOL)deleteCachedToken;
120
121 /**
122  * 用来获得当前sdk的版本号
123  * \return 返回sdk版本号
124  **/
125
126 + (NSString*)sdkVersion;
127
128 /**
129  * 用来获得当前sdk的小版本号
130  * \return 返回sdk小版本号
131  **/
132
133 + (NSString*)sdkSubVersion;
134
135 /**
136  * 用来获得当前sdk的是否精简版
137  * \return 返回YES表示精简版
138  **/
139
140 + (BOOL)isLiteSDK;
141
142 /** 
143  * 主要是用来帮助判断是否有登陆被发起,但是还没有过返回结果 
144  * \return 
145  *          kTencentNotAuthorizeState:无授权 
146  *          kTencentSSOAuthorizeState:有人发起了sso授权但无返回
147  *          kTencentWebviewAuthorzieState:有人发起了webview授权还未返回
148  **/
149
150 + (TencentAuthorizeState *)authorizeState;
151
152 /**
153  * 用来获得当前手机qq的版本号
154  * \return 返回手机qq版本号
155  **/
156 + (int)iphoneQQVersion __attribute__((deprecated("已过期, 建议删除调用")));
157
158
159 /**
160  * 用来获得当前手机TIM的版本号
161  * \return 返回手机qq版本号
162  **/
163 + (int)iphoneTIMVersion __attribute__((deprecated("已过期, 建议删除调用")));
164
165 /**
166  * 初始化TencentOAuth对象
167  * \param appId 第三方应用在互联开放平台申请的唯一标识
168  * \param delegate 第三方应用用于接收请求返回结果的委托对象
169  * \return 初始化后的授权登录对象
170  */
171 - (id)initWithAppId:(NSString *)appId
172         andDelegate:(id<TencentSessionDelegate>)delegate;
173
174 /**
175 * 初始化TencentOAuth对象(>=3.3.7)
176 * \param appId 第三方应用在互联开放平台申请的唯一标识
177 * \param universalLink 第三方应用在互联开放平台注册的universallink,和bundleID一一对应
178 * \param delegate 第三方应用用于接收请求返回结果的委托对象
179 * \return 初始化后的授权登录对象
180 */
181 - (id)initWithAppId:(NSString *)appId
182    andUniversalLink:(NSString *)universalLink
183         andDelegate:(id<TencentSessionDelegate>)delegate;
184
185 /**
186  * 判断用户手机上是否安装手机QQ
187  * \return YES:安装 NO:没安装
188  *
189  * \note SDK目前已经支持QQ、TIM授权登录及分享功能, 会按照QQ>TIM的顺序进行调用。
190  * 只要用户安装了QQ、TIM中任意一个应用,都可为第三方应用进行授权登录、分享功能。
191  * 第三方应用在接入SDK时不需要判断是否安装QQ、TIM。若有判断安装QQ、TIM的逻辑建议移除。
192  */
193 + (BOOL)iphoneQQInstalled;
194
195 /**
196  * 判断用户手机上是否安装手机TIM
197  * \return YES:安装 NO:没安装
198  *
199  * \note SDK目前已经支持QQ、TIM授权登录及分享功能, 会按照QQ>TIM的顺序进行调用。
200  * 只要用户安装了QQ、TIM中任意一个应用,都可为第三方应用进行授权登录、分享功能。
201  * 第三方应用在接入SDK时不需要判断是否安装QQ、TIM。若有判断安装QQ、TIM的逻辑建议移除。
202  */
203 + (BOOL)iphoneTIMInstalled;
204  
205 /**
206  * 判断用户手机上的手机QQ是否支持SSO登录
207  * \return YES:支持 NO:不支持
208  */
209 + (BOOL)iphoneQQSupportSSOLogin __attribute__((deprecated("QQ版本均支持SSO登录。该接口已过期, 建议删除调用")));
210
211 /**
212  * 判断用户手机上的手机TIM是否支持SSO登录
213  * \return YES:支持 NO:不支持
214  */
215 + (BOOL)iphoneTIMSupportSSOLogin __attribute__((deprecated("TIM版本均支持SSO登录。该接口已过期, 建议删除调用")));
216
217 /**
218  * 登录授权
219  *
220  * \param permissions 授权信息列
221  */
222 - (BOOL)authorize:(NSArray *)permissions;
223
224 /**
225  * 登录授权
226  * \param permissions 授权信息列表
227  * \param bInSafari 是否使用safari进行登录.<b>IOS SDK 1.3版本开始此参数废除</b>
228  */
229 - (BOOL)authorize:(NSArray *)permissions
230          inSafari:(BOOL)bInSafari;
231
232 /**
233  * 登录授权
234  * \param permissions 授权信息列表
235  * \param localAppId 应用APPID
236  * \param bInSafari 是否使用safari进行登录.<b>IOS SDK 1.3版本开始此参数废除</b>
237  */
238 - (BOOL)authorize:(NSArray *)permissions
239        localAppId:(NSString *)localAppId
240          inSafari:(BOOL)bInSafari;
241
242 /**
243  * 登录授权<web为二维码扫码方式>
244  *
245  * \param permissions 授权信息列
246  */
247 - (BOOL)authorizeWithQRlogin:(NSArray *)permissions;
248
249 /**
250  * 增量授权,因用户没有授予相应接口调用的权限,需要用户确认是否授权
251  * \param permissions 需增量授权的信息列表
252  * \return 增量授权调用是否成功
253  */
254 - (BOOL)incrAuthWithPermissions:(NSArray *)permissions;
255
256 /**
257  * 重新授权,因token废除或失效导致接口调用失败,需用户重新授权
258  * \param permissions 授权信息列表,同登录授权
259  * \return 授权调用是否成功
260  */
261 - (BOOL)reauthorizeWithPermissions:(NSArray *)permissions;
262
263 /**
264  * 获取UnindID,可以根据UnindID的比较来确定OpenID是否属于同一个用户
265  * \return NO未登录,信息不足;YES条件满足,发送请求成功,请等待回调
266  */
267 - (BOOL)RequestUnionId;
268
269 /**
270  * (静态方法)处理应用拉起协议
271  * \param url 处理被其他应用呼起时的逻辑
272  * \return 处理结果,YES表示成功,NO表示失败
273  */
274 + (BOOL)HandleOpenURL:(NSURL *)url;
275
276 /**
277  * (静态方法)sdk是否可以处理应用拉起协议
278  * \param url 处理被其他应用呼起时的逻辑
279  * \return 处理结果,YES表示可以 NO表示不行
280  */
281 + (BOOL)CanHandleOpenURL:(NSURL *)url;
282
283 /**
284  * (静态方法)处理应用的UniversalLink拉起协议
285  * \param url 处理被其他应用呼起时的逻辑
286  * \return 处理结果,YES表示成功,NO表示失败
287  */
288 + (BOOL)HandleUniversalLink:(NSURL *)url;
289
290 /**
291  * (静态方法)sdk是否可以处理应用的Universallink拉起协议
292  * \param url 处理被其他应用呼起时的逻辑(应用的Universallink链接须满足官网注册时的格式要求)
293  * \return 处理结果,YES表示可以 NO表示不行
294  * 注:在调用其他Universallink相关处理接口之前,均需进行此项判断
295  */
296 + (BOOL)CanHandleUniversalLink:(NSURL *)url;
297
298 /**
299  * (静态方法)获取TencentOAuth调用的上一次错误信息
300  */
301 + (NSString *)getLastErrorMsg;
302
303 /**
304  * 以Server Side Code模式授权登录时,通过此接口获取返回的code值;
305  * 以Client Side Token模式授权登录时,忽略此接口。
306  */
307 - (NSString *)getServerSideCode;
308
309 /**
310  * 退出登录(退出登录后,TecentOAuth失效,需要重新初始化)
311  * \param delegate 第三方应用用于接收请求返回结果的委托对象
312  */
313 - (void)logout:(id<TencentSessionDelegate>)delegate;
314
315 /**
316  * 判断登录态是否有效
317  * \return 处理结果,YES表示有效,NO表示无效,请用户重新登录授权
318  */
319 - (BOOL)isSessionValid;
320
321 /**
322  * 获取用户个人信息
323  * \return 处理结果,YES表示API调用成功,NO表示API调用失败,登录态失败,重新登录
324  */
325 - (BOOL)getUserInfo;
326
327 /**
328  * 退出指定API调用
329  * \param userData 用户调用某条API的时候传入的保留参数
330  * \return 处理结果,YES表示成功 NO表示失败
331  */
332 - (BOOL)cancel:(id)userData;
333
334 /**
335  * CGI类任务创建接口
336  * \param apiURL CGI请求的URL地址
337  * \param method CGI请求方式:"GET","POST"
338  * \param params CGI请求参数字典
339  * \param callback CGI请求结果的回调接口对象
340  * \return CGI请求任务实例,用于取消任务,返回nil代表任务创建失败
341  */
342 - (TCAPIRequest *)cgiRequestWithURL:(NSURL *)apiURL method:(NSString *)method params:(NSDictionary *)params callback:(id<TCAPIRequestDelegate>)callback;
343
344 /**
345  * TencentOpenApi发送任务统一接口
346  * \param request 请求发送的任务
347  * \param callback 任务发送后的回调地址
348  */
349 - (BOOL)sendAPIRequest:(TCAPIRequest *)request callback:(id<TCAPIRequestDelegate>)callback;
350
351 - (NSString *)getUserOpenID;
352
353 @end
354
355 #pragma mark - TencentLoginDelegate(授权登录回调协议)
356
357 /**
358  * \brief TencentLoginDelegate iOS Open SDK 1.3 API回调协议
359  *
360  * 第三方应用实现登录的回调协议
361  */
362 @protocol TencentLoginDelegate <NSObject>
363
364 @required
365
366 /**
367  * 登录成功后的回调
368  */
369 - (void)tencentDidLogin;
370
371 /**
372  * 登录失败后的回调
373  * \param cancelled 代表用户是否主动退出登录
374  */
375 - (void)tencentDidNotLogin:(BOOL)cancelled;
376
377 /**
378  * 登录时网络有问题的回调
379  */
380 - (void)tencentDidNotNetWork;
381
382 @optional
383 /**
384  * 登录时权限信息的获得
385  */
386 - (NSArray *)getAuthorizedPermissions:(NSArray *)permissions withExtraParams:(NSDictionary *)extraParams;
387
388 /**
389  * unionID获得
390  */
391 - (void)didGetUnionID;
392
393 /**
394  * 强制网页登录,包括账号密码登录和二维码登录
395  * return YES时,就算本地有手Q也会打开web界面
396  */
397 - (BOOL)forceWebLogin;
398 @end
399
400 #pragma mark - TencentSessionDelegate(开放接口回调协议)
401
402 /**
403  * \brief TencentSessionDelegate iOS Open SDK 1.3 API回调协议
404  *
405  * 第三方应用需要实现每条需要调用的API的回调协议
406  */
407 @protocol TencentSessionDelegate<NSObject, TencentLoginDelegate,
408                                 TencentWebViewDelegate>
409
410 @optional
411
412 /**
413  * 退出登录的回调
414  */
415 - (void)tencentDidLogout;
416
417 /**
418  * 因用户未授予相应权限而需要执行增量授权。在用户调用某个api接口时,如果服务器返回操作未被授权,则触发该回调协议接口,由第三方决定是否跳转到增量授权页面,让用户重新授权。
419  * \param tencentOAuth 登录授权对象。
420  * \param permissions 需增量授权的权限列表。
421  * \return 是否仍然回调返回原始的api请求结果。
422  * \note 不实现该协议接口则默认为不开启增量授权流程。若需要增量授权请调用\ref TencentOAuth#incrAuthWithPermissions: \n注意:增量授权时用户可能会修改登录的帐号
423  */
424 - (BOOL)tencentNeedPerformIncrAuth:(TencentOAuth *)tencentOAuth withPermissions:(NSArray *)permissions;
425
426 /**
427  * [该逻辑未实现]因token失效而需要执行重新登录授权。在用户调用某个api接口时,如果服务器返回token失效,则触发该回调协议接口,由第三方决定是否跳转到登录授权页面,让用户重新授权。
428  * \param tencentOAuth 登录授权对象。
429  * \return 是否仍然回调返回原始的api请求结果。
430  * \note 不实现该协议接口则默认为不开启重新登录授权流程。若需要重新登录授权请调用\ref TencentOAuth#reauthorizeWithPermissions: \n注意:重新登录授权时用户可能会修改登录的帐号
431  */
432 - (BOOL)tencentNeedPerformReAuth:(TencentOAuth *)tencentOAuth;
433
434 /**
435  * 用户通过增量授权流程重新授权登录,token及有效期限等信息已被更新。
436  * \param tencentOAuth token及有效期限等信息更新后的授权实例对象
437  * \note 第三方应用需更新已保存的token及有效期限等信息。
438  */
439 - (void)tencentDidUpdate:(TencentOAuth *)tencentOAuth;
440
441 /**
442  * 用户增量授权过程中因取消或网络问题导致授权失败
443  * \param reason 授权失败原因,具体失败原因参见sdkdef.h文件中\ref UpdateFailType
444  */
445 - (void)tencentFailedUpdate:(UpdateFailType)reason;
446
447 /**
448  * 获取用户个人信息回调
449  * \param response API返回结果,具体定义参见sdkdef.h文件中\ref APIResponse
450  * \remarks 正确返回示例: \snippet example/getUserInfoResponse.exp success
451  *          错误返回示例: \snippet example/getUserInfoResponse.exp fail
452  */
453 - (void)getUserInfoResponse:(APIResponse*) response;
454
455 /**
456  * 社交API统一回调接口
457  * \param response API返回结果,具体定义参见sdkdef.h文件中\ref APIResponse
458  * \param message 响应的消息,目前支持‘SendStory’,‘AppInvitation’,‘AppChallenge’,‘AppGiftRequest’
459  */
460 - (void)responseDidReceived:(APIResponse*)response forMessage:(NSString *)message;
461
462 /**
463  * post请求的上传进度
464  * \param tencentOAuth 返回回调的tencentOAuth对象
465  * \param bytesWritten 本次回调上传的数据字节数
466  * \param totalBytesWritten 总共已经上传的字节数
467  * \param totalBytesExpectedToWrite 总共需要上传的字节数
468  * \param userData 用户自定义数据
469  */
470 - (void)tencentOAuth:(TencentOAuth *)tencentOAuth didSendBodyData:(NSInteger)bytesWritten totalBytesWritten:(NSInteger)totalBytesWritten totalBytesExpectedToWrite:(NSInteger)totalBytesExpectedToWrite userData:(id)userData;
471
472
473 /**
474  * 通知第三方界面需要被关闭
475  * \param tencentOAuth 返回回调的tencentOAuth对象
476  * \param viewController 需要关闭的viewController
477  */
478 - (void)tencentOAuth:(TencentOAuth *)tencentOAuth doCloseViewController:(UIViewController *)viewController;
479
480 @end
481
482 #pragma mark - TencentWebViewDelegate(H5登录webview旋转方向回调)
483
484 /**
485  * \brief TencentWebViewDelegate: H5登录webview旋转方向回调协议
486  *
487  * 第三方应用可以根据自己APP的旋转方向限制,通过此协议设置
488  */
489 @protocol TencentWebViewDelegate <NSObject>
490 @optional
491 - (BOOL) tencentWebViewShouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)toInterfaceOrientation;
492 - (NSUInteger) tencentWebViewSupportedInterfaceOrientationsWithWebkit;
493 - (BOOL) tencentWebViewShouldAutorotateWithWebkit;
494 @end