APIバージョン:1.3
中国語版へのリンク
-
iOS SDKのダウンロード
SDKのダウンロードページ -
SDKの構成
iOS SDK v1.3は下記の二つから構成されている。 -
SDKをプロジェクトに埋め込む
-
app_idの設定
-
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]; }
-
TencentSessionDelegateのプロトコルを実装する。 具体的には、TencentOpenAPI/TencentOAuth.h を参照してください。
-
認証オブジェクトのインスタンス初期化と設定。
-
初期化
self.tencentOAuth = [[TencentOAuth alloc] initWithAppId:@"app_id", andDelegate:self]; //selfはTencentSessionDelegateのインスタンスです。
-
redirectURIの設定(redirectURIはこのアプリをTensentに登録する時のリダイレクトURIです。略してもOKなので、登録しないほうがよい。)
self.tencentOAuth.redirectURI = @"uri";
-
ユーザーに許可させたいAPIの配列を設定する。 APIの一覧はこちら
self.permissions = @[@"get_user_info", @"add_share"];
-
-
SDKでのログインフロー
-
authorizeを呼び出す。すると、アプリはログイン画面に遷移する。
[self.tentcentOAuth authorize:self.permissions inSafari:NO];
-
認証された後、認証結果によって、デリゲートメソッドが呼び出される。
-
正常に終った場合
@protocol TencentSessionDelegate <NSObject> - (void)tencentDidLogin { //ログイン成功 if (self.tencentOAuth.accessToken && 0 != [self.tencentOAuth.accessToken length]) { // ユーザーID、accesstoken、有効期限を取得 NSString *openId = self.tencentOAuth.openId; NSString *accessToken = self.tencentOAuth.accessToken; NSDate *expirationDate = self.tencentOAuth.expirationDate; } else { //access tokenが取得できないため、ログイン失敗になる } }
-
認証失敗した場合
@protocol TencentSessionDelegate <NSObject> -(void)tencentDidNotLogin:(BOOL)cancelled { if (cancelled) { //ユーザーがキャンセルした } else { //ログイン失敗した } }
-
認証の時にネットワーク通信エラーの場合
@protocol TencentSessionDelegate <NSObject> -(void)tencentDidNotNetWork { //ネットワーク通信エラー }
-
要注意のところ
-
認証中はユーザーの操作のため、デリゲートメソッドが呼び出されない可能性もあるので、デリゲートメソッドをずっと待つことをしないでください。
-
access tokenの有効期間は3ヶ月なので、期間切れたら、ユーザーに再ログインさせるロジックが必要です。
-
アプリ側はユーザーID、accesstoken、有効期限を保存できるが、期間切れる前に、保存された情報を使って、認証用のオブジェクトを初期化してもいいです。
[this.tencentOAuth setAccessToken:accessToken]; [this.tencentOAuth setOpenId:openId]; [this.tencentOAuth setExpirationDate:expirationDate];
-
ユーザー体験を一致にするために、ユーザーがログインしてから、getUserInfo APIを使って、ユーザーの画像、ニックネームなどを更新して、表示させたほうがよい。
-
-
他のAPIの呼び出し方
APIの一覧はこちら 以下、ユーザーアバター画像を設定するAPIを例として、説明する。-
各APIを呼び出すときに、パラメーターをNSDictionaryのインスタンスに入れる必要なので、ヘルパークラスを使うなら、便利になります。そのヘルパークラスの名は「
TC{API名}Dic
」となる。
例えば、コンテンツをシェアするAPIのメソッドは- addShareWithParams:params
です。それに応じて、パラメーターのヘルパークラスの名はTCAddShareDic
です。各ヘルパーでは下記のようなプロパティ定義があります:
@property (nonatomic, retain) TCRequiredStr paramTitle;
そのデータタイプのパタンは下記の通りです。
- TCRequiredStr 必須で、文字列パラメーター
- TCOptionalStr オプションで、文字列パラメーター
-
setUserHeadpic(ユーザーアバターの設定)の呼び出す例
TCSetUserHeadpic *params = [TCSetUserHeadpic dictionary]; params.paramImage = image; params.paramFileName = @"make"; [self.tencentOAuth setUserHeadpic:params]
結果が帰って来たら、
- 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:@"OK" otherButtonTitles: nil]; [alert show]; [alert release]; } }
-
返却値の説明
APIResponseのプロバティ- retCode 結果コード
- seq リクエストのシーケンス番号
- errorMsg エラーメッセージ
- jsonResponse json形のレスポンス情報 具体的には、各APIのドキュメントを参照してください。
- message 結果のメッセージ
- detailRetCode v1.2以降追加されています。結果コードの補足情報(具体的なエラー原因)
-
retCode
- 0 操作成功
- 1 操作失敗、原因は下記のdetailRetCodeから調べられる
-
detailRetCode
- kOpenSDKInvalid API無効
共通エラーコード
- kOpenSDKErrorSuccess - 操作成功
- kOpenSDKErrorUnknown - 未知エラー
- kOpenSDKErrorUserCancel - ユーザーが操作をキャンセルした
- kOpenSDKErrorReLogin - tokenが無効になったため、再認証が必要
- kOpenSDKErrorOperationDeny - 権限無し(認証の時に、permission未指定)
ネットワーク通信に関してのエラーコード
- kOpenSDKErrorNetwork - 通信エラー、サーバーへアクセスできなかった
- kOpenSDKErrorURL - URLフォマートかプロトコルエラー
- kOpenSDKErrorDataParse - サーバー側はパラメーター解析できなかった
- kOpenSDKErrorParam - パラメーター不正
- kOpenSDKErrorConnTimeout - http接続タイムアウト
- kOpenSDKErrorSecurity - セキュリティに問題があった
- kOpenSDKErrorIO - ファイルダウンロードにIOエラーが発生した
- kOpenSDKErrorServer - サーバー側はエラーが発生した
ウェブビューにおけるエラーコード
- kOpenSDKErrorWebPage - ウェブページエラー
ユーザーアバター専用のエラーコード
- kOpenSDKErrorUserHeadPicLarge - 画像サイズが大きすぎる
-
-
QZoneでのシングルサインオン
SDK v1.3より、iOSのQZone(TencentのiOSポータルアプリ)を対応している。実装上の手間掛からなくて、QZoneのシングルサインオン機能が使えるようになる。ユーザーの端末ではQZoneがインストールされているなら、自動的にQZoneのログイン画面に遷移するが、QZoneがない端末では、普通のウェブビューログイン画面が開く。