lpw
2021-02-02 8822d61676c5b690c260cbaa0d76c393fdd04525
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  * 获取上次登录得到的token
93  *
94  **/
95 - (NSString *)getCachedToken;
96
97 /**
98  * 获取上次登录得到的openid
99  *
100  **/
101 - (NSString *)getCachedOpenID;
102
103 /**
104  * 获取上次登录的token过期日期
105  *
106  **/
107 - (NSDate *)getCachedExpirationDate;
108
109 /**
110  * 上次登录的token是否过期(本地判断)
111  **/
112 - (BOOL)isCachedTokenValid;
113
114 /**
115  * 删除上次登录登录的token信息
116  *
117  **/
118 - (BOOL)deleteCachedToken;
119
120 /**
121  * 用来获得当前sdk的版本号
122  * \return 返回sdk版本号
123  **/
124
125 + (NSString*)sdkVersion;
126
127 /**
128  * 用来获得当前sdk的小版本号
129  * \return 返回sdk小版本号
130  **/
131
132 + (NSString*)sdkSubVersion;
133
134 /**
135  * 用来获得当前sdk的是否精简版
136  * \return 返回YES表示精简版
137  **/
138
139 + (BOOL)isLiteSDK;
140
141 /** 
142  * 主要是用来帮助判断是否有登陆被发起,但是还没有过返回结果 
143  * \return 
144  *          kTencentNotAuthorizeState:无授权 
145  *          kTencentSSOAuthorizeState:有人发起了sso授权但无返回
146  *          kTencentWebviewAuthorzieState:有人发起了webview授权还未返回
147  **/
148
149 + (TencentAuthorizeState *)authorizeState;
150
151 /**
152  * 初始化TencentOAuth对象
8822d6 153  * \param appId 不可为nil,第三方应用在互联开放平台申请的唯一标识
L 154  * \param delegate 不可为nil,第三方应用用于接收请求返回结果的委托对象
eec5d6 155  * \return 初始化后的授权登录对象
L 156  */
157 - (id)initWithAppId:(NSString *)appId
158         andDelegate:(id<TencentSessionDelegate>)delegate;
159
160 /**
161 * 初始化TencentOAuth对象(>=3.3.7)
8822d6 162 * \param appId 不可为nil,第三方应用在互联开放平台申请的唯一标识
L 163 * \param universalLink 可以为nil,第三方应用在互联开放平台注册的UniversalLink,和bundleID一一对应(当为nil时,互联平台会按规则生成universallink,详见官网说明)
164 * \param delegate 不可为nil,第三方应用用于接收请求返回结果的委托对象
eec5d6 165 * \return 初始化后的授权登录对象
8822d6 166 *
L 167 ****【使用说明】*****
168 * 1、支持BundleId与UniversalLink的一一对应,主要目的“是为了解决应用的iPhone版本和iPad HD版本共用同一个AppId,导致同时安装情况下的跳转问题"。
169 * 2 、由于手Q版本在 >=8.1.8 后才支持了这种对应方式,所以一旦使用,“务必做到”及时知会用户升级手Q版本。
170 ****
eec5d6 171 */
L 172 - (id)initWithAppId:(NSString *)appId
173    andUniversalLink:(NSString *)universalLink
174         andDelegate:(id<TencentSessionDelegate>)delegate;
8822d6 175
L 176 /**
177 * 初始化TencentOAuth对象(>=3.3.8)
178 * \param appId 不可为nil,第三方应用在互联开放平台申请的唯一标识
179 * \param enabled  默认为NO,第三方应用是否将sdk和手机QQ的交互方式切换为UniversalLink方式,启用后则在iOS9及以上的系统都会生效UniversalLink方式;否则,默认仅在iOS13及以上的系统生效UniversalLink方式。
180 * \param universalLink 可以为nil,第三方应用在互联开放平台注册的UniversalLink,和bundleID一一对应(当为nil时,互联平台会按规则生成UniversalLink,详见官网说明)
181 * \param delegate 不可为nil,第三方应用用于接收请求返回结果的委托对象
182 * \return 初始化后的授权登录对象
183 *
184 *****【使用说明】*****
185 *  1、支持sdk与手Q的交互切换为UniversalLink模式,主要目的"是为了避免手Q的UrlScheme被其他应用抢注后,导致sdk接口功能受到影响"。
186 *  2 、由于手Q版本在 >=8.1.3 后才适配了UniversalLink,所以一旦开启了enabled开关,“务必做到”及时知会用户升级手Q版本。
187 *****
188 */
189 - (id)initWithAppId:(NSString *)appId
190  enableUniveralLink:(BOOL)enabled
191       universalLink:(NSString *)universalLink
192            delegate:(id<TencentSessionDelegate>)delegate;
eec5d6 193
L 194 /**
195  * 判断用户手机上是否安装手机QQ
196  * \return YES:安装 NO:没安装
197  *
198  * \note SDK目前已经支持QQ、TIM授权登录及分享功能, 会按照QQ>TIM的顺序进行调用。
199  * 只要用户安装了QQ、TIM中任意一个应用,都可为第三方应用进行授权登录、分享功能。
200  * 第三方应用在接入SDK时不需要判断是否安装QQ、TIM。若有判断安装QQ、TIM的逻辑建议移除。
201  */
202 + (BOOL)iphoneQQInstalled;
203
204 /**
205  * 判断用户手机上是否安装手机TIM
206  * \return YES:安装 NO:没安装
207  *
208  * \note SDK目前已经支持QQ、TIM授权登录及分享功能, 会按照QQ>TIM的顺序进行调用。
209  * 只要用户安装了QQ、TIM中任意一个应用,都可为第三方应用进行授权登录、分享功能。
210  * 第三方应用在接入SDK时不需要判断是否安装QQ、TIM。若有判断安装QQ、TIM的逻辑建议移除。
211  */
212 + (BOOL)iphoneTIMInstalled;
213  
214 /**
215  * 登录授权
216  *
217  * \param permissions 授权信息列
218  */
219 - (BOOL)authorize:(NSArray *)permissions;
220
221 /**
222  * 登录授权
223  * \param permissions 授权信息列表
224  * \param localAppId 应用APPID
225  */
226 - (BOOL)authorize:(NSArray *)permissions
8822d6 227        localAppId:(NSString *)localAppId;
eec5d6 228
L 229 /**
230  * 登录授权<web为二维码扫码方式>
231  *
232  * \param permissions 授权信息列
233  */
234 - (BOOL)authorizeWithQRlogin:(NSArray *)permissions;
235
236 /**
237  * 增量授权,因用户没有授予相应接口调用的权限,需要用户确认是否授权
238  * \param permissions 需增量授权的信息列表
239  * \return 增量授权调用是否成功
240  */
241 - (BOOL)incrAuthWithPermissions:(NSArray *)permissions;
242
243 /**
244  * 重新授权,因token废除或失效导致接口调用失败,需用户重新授权
245  * \param permissions 授权信息列表,同登录授权
246  * \return 授权调用是否成功
247  */
248 - (BOOL)reauthorizeWithPermissions:(NSArray *)permissions;
249
250 /**
251  * 获取UnindID,可以根据UnindID的比较来确定OpenID是否属于同一个用户
252  * \return NO未登录,信息不足;YES条件满足,发送请求成功,请等待回调
253  */
254 - (BOOL)RequestUnionId;
255
256 /**
257  * (静态方法)处理应用拉起协议
258  * \param url 处理被其他应用呼起时的逻辑
259  * \return 处理结果,YES表示成功,NO表示失败
260  */
261 + (BOOL)HandleOpenURL:(NSURL *)url;
262
263 /**
264  * (静态方法)sdk是否可以处理应用拉起协议
265  * \param url 处理被其他应用呼起时的逻辑
266  * \return 处理结果,YES表示可以 NO表示不行
267  */
268 + (BOOL)CanHandleOpenURL:(NSURL *)url;
269
270 /**
271  * (静态方法)处理应用的UniversalLink拉起协议
272  * \param url 处理被其他应用呼起时的逻辑
273  * \return 处理结果,YES表示成功,NO表示失败
274  */
275 + (BOOL)HandleUniversalLink:(NSURL *)url;
276
277 /**
278  * (静态方法)sdk是否可以处理应用的Universallink拉起协议
279  * \param url 处理被其他应用呼起时的逻辑(应用的Universallink链接须满足官网注册时的格式要求)
280  * \return 处理结果,YES表示可以 NO表示不行
281  * 注:在调用其他Universallink相关处理接口之前,均需进行此项判断
282  */
283 + (BOOL)CanHandleUniversalLink:(NSURL *)url;
284
285 /**
286  * (静态方法)获取TencentOAuth调用的上一次错误信息
287  */
288 + (NSString *)getLastErrorMsg;
289
290 /**
291  * 以Server Side Code模式授权登录时,通过此接口获取返回的code值;
292  * 以Client Side Token模式授权登录时,忽略此接口。
293  */
294 - (NSString *)getServerSideCode;
295
296 /**
297  * 退出登录(退出登录后,TecentOAuth失效,需要重新初始化)
298  * \param delegate 第三方应用用于接收请求返回结果的委托对象
299  */
300 - (void)logout:(id<TencentSessionDelegate>)delegate;
301
302 /**
303  * 判断登录态是否有效
304  * \return 处理结果,YES表示有效,NO表示无效,请用户重新登录授权
305  */
306 - (BOOL)isSessionValid;
307
308 /**
309  * 获取用户个人信息
310  * \return 处理结果,YES表示API调用成功,NO表示API调用失败,登录态失败,重新登录
311  */
312 - (BOOL)getUserInfo;
313
314 /**
315  * 退出指定API调用
316  * \param userData 用户调用某条API的时候传入的保留参数
317  * \return 处理结果,YES表示成功 NO表示失败
318  */
319 - (BOOL)cancel:(id)userData;
320
321 /**
322  * CGI类任务创建接口
323  * \param apiURL CGI请求的URL地址
324  * \param method CGI请求方式:"GET","POST"
325  * \param params CGI请求参数字典
326  * \param callback CGI请求结果的回调接口对象
327  * \return CGI请求任务实例,用于取消任务,返回nil代表任务创建失败
328  */
329 - (TCAPIRequest *)cgiRequestWithURL:(NSURL *)apiURL method:(NSString *)method params:(NSDictionary *)params callback:(id<TCAPIRequestDelegate>)callback;
330
331 /**
332  * TencentOpenApi发送任务统一接口
333  * \param request 请求发送的任务
334  * \param callback 任务发送后的回调地址
335  */
336 - (BOOL)sendAPIRequest:(TCAPIRequest *)request callback:(id<TCAPIRequestDelegate>)callback;
337
338 - (NSString *)getUserOpenID;
339
340 @end
341
342 #pragma mark - TencentLoginDelegate(授权登录回调协议)
343
344 /**
345  * \brief TencentLoginDelegate iOS Open SDK 1.3 API回调协议
346  *
347  * 第三方应用实现登录的回调协议
348  */
349 @protocol TencentLoginDelegate <NSObject>
350
351 @required
352
353 /**
354  * 登录成功后的回调
355  */
356 - (void)tencentDidLogin;
357
358 /**
359  * 登录失败后的回调
360  * \param cancelled 代表用户是否主动退出登录
361  */
362 - (void)tencentDidNotLogin:(BOOL)cancelled;
363
364 /**
365  * 登录时网络有问题的回调
366  */
367 - (void)tencentDidNotNetWork;
368
369 @optional
370 /**
371  * 登录时权限信息的获得
372  */
8822d6 373 - (NSArray *)getAuthorizedPermissions:(NSArray *)permissions withExtraParams:(NSDictionary *)extraParams __attribute__((deprecated("该接口已过期, 建议删除调用")));
eec5d6 374
L 375 /**
376  * unionID获得
377  */
378 - (void)didGetUnionID;
379
380 /**
381  * 强制网页登录,包括账号密码登录和二维码登录
382  * return YES时,就算本地有手Q也会打开web界面
383  */
384 - (BOOL)forceWebLogin;
385 @end
386
387 #pragma mark - TencentSessionDelegate(开放接口回调协议)
388
389 /**
390  * \brief TencentSessionDelegate iOS Open SDK 1.3 API回调协议
391  *
392  * 第三方应用需要实现每条需要调用的API的回调协议
393  */
394 @protocol TencentSessionDelegate<NSObject, TencentLoginDelegate,
395                                 TencentWebViewDelegate>
396
397 @optional
398
399 /**
400  * 退出登录的回调
401  */
402 - (void)tencentDidLogout;
403
404 /**
405  * 因用户未授予相应权限而需要执行增量授权。在用户调用某个api接口时,如果服务器返回操作未被授权,则触发该回调协议接口,由第三方决定是否跳转到增量授权页面,让用户重新授权。
406  * \param tencentOAuth 登录授权对象。
407  * \param permissions 需增量授权的权限列表。
408  * \return 是否仍然回调返回原始的api请求结果。
409  * \note 不实现该协议接口则默认为不开启增量授权流程。若需要增量授权请调用\ref TencentOAuth#incrAuthWithPermissions: \n注意:增量授权时用户可能会修改登录的帐号
410  */
411 - (BOOL)tencentNeedPerformIncrAuth:(TencentOAuth *)tencentOAuth withPermissions:(NSArray *)permissions;
412
413 /**
414  * [该逻辑未实现]因token失效而需要执行重新登录授权。在用户调用某个api接口时,如果服务器返回token失效,则触发该回调协议接口,由第三方决定是否跳转到登录授权页面,让用户重新授权。
415  * \param tencentOAuth 登录授权对象。
416  * \return 是否仍然回调返回原始的api请求结果。
417  * \note 不实现该协议接口则默认为不开启重新登录授权流程。若需要重新登录授权请调用\ref TencentOAuth#reauthorizeWithPermissions: \n注意:重新登录授权时用户可能会修改登录的帐号
418  */
419 - (BOOL)tencentNeedPerformReAuth:(TencentOAuth *)tencentOAuth;
420
421 /**
422  * 用户通过增量授权流程重新授权登录,token及有效期限等信息已被更新。
423  * \param tencentOAuth token及有效期限等信息更新后的授权实例对象
424  * \note 第三方应用需更新已保存的token及有效期限等信息。
425  */
426 - (void)tencentDidUpdate:(TencentOAuth *)tencentOAuth;
427
428 /**
429  * 用户增量授权过程中因取消或网络问题导致授权失败
430  * \param reason 授权失败原因,具体失败原因参见sdkdef.h文件中\ref UpdateFailType
431  */
432 - (void)tencentFailedUpdate:(UpdateFailType)reason;
433
434 /**
435  * 获取用户个人信息回调
436  * \param response API返回结果,具体定义参见sdkdef.h文件中\ref APIResponse
437  * \remarks 正确返回示例: \snippet example/getUserInfoResponse.exp success
438  *          错误返回示例: \snippet example/getUserInfoResponse.exp fail
439  */
440 - (void)getUserInfoResponse:(APIResponse*) response;
441
442 /**
443  * 社交API统一回调接口
444  * \param response API返回结果,具体定义参见sdkdef.h文件中\ref APIResponse
445  * \param message 响应的消息,目前支持‘SendStory’,‘AppInvitation’,‘AppChallenge’,‘AppGiftRequest’
446  */
447 - (void)responseDidReceived:(APIResponse*)response forMessage:(NSString *)message;
448
449 /**
450  * post请求的上传进度
451  * \param tencentOAuth 返回回调的tencentOAuth对象
452  * \param bytesWritten 本次回调上传的数据字节数
453  * \param totalBytesWritten 总共已经上传的字节数
454  * \param totalBytesExpectedToWrite 总共需要上传的字节数
455  * \param userData 用户自定义数据
456  */
457 - (void)tencentOAuth:(TencentOAuth *)tencentOAuth didSendBodyData:(NSInteger)bytesWritten totalBytesWritten:(NSInteger)totalBytesWritten totalBytesExpectedToWrite:(NSInteger)totalBytesExpectedToWrite userData:(id)userData;
458
459
460 /**
461  * 通知第三方界面需要被关闭
462  * \param tencentOAuth 返回回调的tencentOAuth对象
463  * \param viewController 需要关闭的viewController
464  */
465 - (void)tencentOAuth:(TencentOAuth *)tencentOAuth doCloseViewController:(UIViewController *)viewController;
466
467 @end
468
469 #pragma mark - TencentWebViewDelegate(H5登录webview旋转方向回调)
470
471 /**
472  * \brief TencentWebViewDelegate: H5登录webview旋转方向回调协议
473  *
474  * 第三方应用可以根据自己APP的旋转方向限制,通过此协议设置
475  */
476 @protocol TencentWebViewDelegate <NSObject>
477 @optional
478 - (BOOL) tencentWebViewShouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)toInterfaceOrientation;
479 - (NSUInteger) tencentWebViewSupportedInterfaceOrientationsWithWebkit;
480 - (BOOL) tencentWebViewShouldAutorotateWithWebkit;
481 @end