tencent cloud

Tencent Cloud EdgeOne

iOSインテグレーション手順

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-10-15 18:07:46
AI翻訳

概要

本文档では、EdgeOne クライアント認証 SDK を iOS プロジェクトに統合する具体的な手順について詳しく説明します。これには、SDK の導入、権限設定、初期化、認証エンジンの起動、チャレンジ処理、および API リクエストでのトークンの使用が含まれます。

統合手順

注意:
統合を開始する前に、モバイル統合概要を読み、内容を理解し、モバイルの基本的な認証フローを把握していることを確認してください。

1. EdgeOne SDKをプロジェクトに追加する

EdgeOne クライアント認証 SDK を iOS プロジェクトに統合することが最初の手順です。CocoaPods を使用して SDK を導入できます。お使いの Podfile に以下の内容を追加してください:
pod 'ClientAttestation', :podspec => './SDK' // 設定例です。実際のSDK podspecアドレスに置き換えてください。
その後、以下のコマンドを実行します:
pod install

2. SDKを初期化する

認証機能を使用する前に、お客様のサービスドメインと任意のログレベルを使用して EdgeOne SDK を初期化する必要があります。この操作は通常、お客様の AppDelegate またはアプリケーション起動時に一度実行されます。
#import <TCBasCommon/TCBasCommon.h>
#import <ClientAttestation/ClientAttestation.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// SDK初期化
TCBasConfig *basConfig = [[TCBasConfig alloc] init];
basConfig.baseUrl = @"www.example.com"; // 業務ドメインに設定します。
basConfig.logLevel = TCBCLogLevelTypeWARN; // 任意:ログレベルを設定します。
[TCBas initializeWithOptions:basConfig];
return YES;
}
パラメータの説明:
baseUrl:お客様の EdgeOne サービスドメインです。例:www.example.com。
logLevel:任意パラメータです。SDKのログ出力レベルを制御するために使用されます。選択可能な値は以下の通りです:
TCBCLogLevelTypeNONE:ログを無効にします(デフォルト)。
TCBCLogLevelTypeVERBOSE:verbose 以上のレベルのログを有効にします。
TCBCLogLevelTypeDEBUG:debug 以上のレベルのログを有効にします。
TCBCLogLevelTypeINFO:info 以上のレベルのログを有効にします。
TCBCLogLevelTypeWARN:warning 以上のレベルのログを有効にします。
TCBCLogLevelTypeERROR:error 以上のレベルのログを有効にします。
extraDataProvider:任意パラメータです。IDFVを設定し、リスク識別能力を向上させます。

3. 認証エンジンを起動する

SDKの初期化が完了した後、クライアント認証エンジンを起動する必要があります。これにより、SDKは認証トークンの取得と管理を開始できます。この操作により、SDK内部で必要なバックグラウンドプロセスが起動します。
#import <ClientAttestation/ClientAttestation.h>

クライアント認証エンジンを起動します。
[[ClientAttestation sharedInstance] start];
注意:認証エンジンの起動後、SDKは認証チャレンジの処理と認証トークンの管理を実行できる状態になります。

4. クライアント認証チャレンジを実行する

認証チャレンジは、認証トークンを取得するための重要なステップです。このプロセスでは、チャレンジIDを取得し、それをSDKに渡します。SDKは、必要に応じて必要なUIを表示し(例えば、WKWebViewにCaptchaを表示します)、認証トークンを計算します。これは、SDKが提供するattestWithParams()メソッドによって実行されます。
#import <ClientAttestation/ClientAttestation.h>

// attestId
// 主動的にチャレンジを開始する際にコンソールから取得します。
// 受動的にチャレンジが開始された際に、httpが返すheaderフィールド内の「EO-Attest-Challenge」から取得します。
NSString *attestId = @"your-attestId";
AttestParams *params = [[AttestParams alloc] init];
params.attestId = attestId;
params.webView = self.webView; // Captcha画面の表示に使用するWebViewです。
params.reqTimeoutMillis = 60000; // オプション、リクエストタイムアウト時間です。
[[ClientAttestation sharedInstance] attestWithParams:params
callback:self];

// AttestCallbackDelegateプロトコルを実装します。
#pragma mark - AttestCallbackDelegate
- (void)onSuccess:(NSString *)token {
// リスクチケットを返し、チケットをhttpリクエストのheaderフィールド「EO-Attest-Token」に配置します。
}

- (void)onError:(NSError *)error {
// エラーメッセージのコールバック
}
パラメータの説明:
attestId: チャレンジIDを設定します。コンソールから取得するか、リクエスト結果から返されます。
webView: オプションのパラメータで、WKWebViewインスタンスです。認証器がユーザー操作(Captchaなど)を必要とする場合、このパラメータを提供する必要があります。UI操作が不要な場合、WKWebViewは非表示にすることができます。
vCodeDispType: オプションのパラメータで、インタラクティブなCaptcha UIの表示モードです。ポップアップ全画面枠で表示する場合はVCodeDispTypePopupを使用し、ページ内に埋め込んで表示する場合はVCodeDispTypeFullを使用します。デフォルト値:VCodeDispTypePopup。
reqTimeoutMillis: オプションのパラメータで、リクエストタイムアウト時間を設定します。単位:ミリ秒、デフォルトは60000ミリ秒です。

5. APIリクエストに認証トークンを含める

iOSアプリがEdgeOneによって保護されたバックエンドサービスにAPIリクエストを送信する場合、必ずリクエストヘッダーに認証トークンを含めてください。SDKが提供するgetAttestationToken()メソッドを呼び出すことで、現在有効な認証トークンをいつでも取得できます。
注意:
attestWithParams() の呼び出しが成功するたびに、SDK は認証トークンを生成または更新します。トークンをリクエストヘッダーに付与する前に、必ず再度 getAttestationToken() を呼び出して最新のトークンを取得してください。トークンデータを使用する必要があるたびに、新しいトークンデータを再取得してください。getAttestationToken() が返すトークンデータを保存または再利用しないでください。
#import <ClientAttestation/ClientAttestation.h>

// クライアント認証チケットを取得します。
[[ClientAttestation sharedInstance] getAttestationTokenWithCompletion:^(NSString *token) {
// 例:トークンをネットワークリクエストヘッダーに追加します。
// URLSession または他のネットワークライブラリを使用していると仮定します。
if (token) {
// リクエストオブジェクト
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://your-backend-api.com/data"]];
[request setValue:token forHTTPHeaderField:@"EO-Attest-Token"];
// 引き続きリクエストを送信します。
}
}];
重要なお知らせ: 認証が必要なすべてのAPIリクエストにこのトークンを含めてください。SDKがトークンのライフサイクルを自動的に管理するため、リクエストを送信する前に最新のトークンを取得するだけで済みます。

6. サーバーレスポンスとチャレンジを処理する

お客様のバックエンドサービス(EdgeOne によって保護されている)がクライアントリクエストを受信すると、リクエストに有効な認証トークンが含まれているかどうかを確認します。リクエストに認証が必要であるにもかかわらず有効なトークンが含まれていない場合、サーバーは HTTP 428 ステータスコードを返し、クライアントに追加認証が必要であることを示します。これは、iOS クライアント統合において開発者が能動的に対応する必要がある重要なポイントです。
お客様のiOSアプリは、これらのHTTP 428レスポンスをキャプチャして処理するメカニズムを実装する必要があります。詳細なフローについては、認証トークンの再取得、または期限切れ認証トークンの更新(HTTP 428チャレンジの処理)を参照してください。
以下は、HTTP 428チャレンジを処理する簡略化された例です。
#import <ClientAttestation/ClientAttestation.h>

// ネットワークリクエスト処理ロジックを想定します。
- (void)sendAPIRequest:(NSMutableURLRequest *)request {
NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
if (error) {
NSLog(@"ネットワークリクエストエラー: %@", error.localizedDescription);
return;
}
NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *)response;
if (httpResponse.statusCode == 428) {
// 428チャレンジを受信し、チャレンジIDを抽出します。
NSString *challengeId = httpResponse.allHeaderFields[@"EO-Attest-Challenge"];
if (challengeId) {
NSLog(@"428チャレンジを受信しました。チャレンジID:%@", challengeId);
// 認証チャレンジを実行します。
AttestParams *attestParams = [[AttestParams alloc] init];
attestParams.attestId = challengeId;
attestParams.webView = self.webView;
[[ClientAttestation sharedInstance] attestWithParams:attestParams callback:self];
// 注意:ここではAttestCallbackDelegateのコールバックを処理し、onSuccessでリクエストを再送信する必要があります。
} else {
NSLog(@"428 レスポンスに EO-Attest-Challenge ヘッダーが見つかりません");
}
} else if (httpResponse.statusCode == 200) {
NSLog(@"リクエスト成功!");
// 業務データを処理します。
} else {
NSLog(@"リクエスト失敗、ステータスコード: %ld", (long)httpResponse.statusCode);
// その他のエラーを処理します。
}
}];
[task resume];
}

// サンプル呼び出し
// NSMutableURLRequest *initialRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://your-backend-api.com/protected-data"]];
// [self sendAPIRequest:initialRequest];

// AttestCallbackDelegateのonSuccessメソッドでリクエストを再送信します。
#pragma mark - AttestCallbackDelegate
- (void)onSuccess:(NSString *)token {
NSLog(@"チャレンジ成功、新しいトークンを取得しました: %@", token);
// 元のリクエストを新しいトークン付きで再送信します。
// ここでは以前のリクエストオブジェクトを取得し、再送信する必要があります。
// 例:
// NSMutableURLRequest *retryRequest = [self.lastFailedRequest mutableCopy]; // 前回失敗したリクエストを保存していることを前提とします。
// [retryRequest setValue:token forHTTPHeaderField:@"EO-Attest-Token"];
// [self sendAPIRequest:retryRequest];
}

- (void)onError:(NSError *)error {
NSLog(@"認証チャレンジ失敗: %@", error.localizedDescription);
}

7. (オプション)WKWebViewを使用したインタラクティブ認証(およびJS認証)

一部のクライアント認証シナリオでは、認証器がユーザー操作(例:インタラクティブなCaptcha)を必要とする場合や、計算集約型タスク(例:暗号化による作業証明)を実行する場合があります。このとき、EdgeOne SDKには特定の実行環境のサポートが必要です。モバイルプラットフォームでは、WKWebView(iOSプラットフォーム)がこれらの機能を実現するための重要なコンポーネントです。
認証器がインタラクティブな CAPTCHA をレンダリングする必要がある場合、または JavaScript ベースの暗号化による Proof-of-Work チャレンジを実行する必要がある場合、SDK は attestWithParams() メソッドを呼び出す際に WKWebView インスタンスを提供することを要求します。これは、開発者がアプリケーション内で事前に WKWebView インスタンスを割り当て、認証 API を呼び出す際にそれをパラメータとして SDK に渡す必要があることを意味します。

対話型認証シナリオ

一部の認証器(例えば、埋め込み型またはポップアップ型のインタラクティブ設定を使用する TC-CAPTCHA)は、インタラクティブインターフェースをレンダリングするために WKWebView インスタンスを必要とします。この WKWebView インスタンスはアプリケーション内部で Captcha ページを表示するため、正しく表示されるように事前に設定する必要があります。
埋め込み型インタラクティブ認証: Captcha インターフェースは固定ブロック形式でデバイス画面に表示されます。UI が正しく表示され、ユーザーエクスペリエンスに影響を与えないようにするために、開発者はレンダリングウィンドウのサイズ、重なり順、配置方法を事前に設定する必要があります。なお、埋め込み型認証 GUI は画面ビューに応じて拡大縮小されません。例えば、TC-CAPTCHA 埋め込み型モードでは、最適なレンダリング効果とユーザーインタラクション体験を得るために、少なくとも 300x230 ピクセルのスペースを確保することを推奨します。
ポップアップ型インタラクティブ認証: Captcha インターフェースは、認証が呼び出された際にフローティングウィンドウ形式でデバイス画面に表示されます。埋め込み型認証と同様に、レンダリングウィンドウのサイズ、重なり順、配置方法も事前に設定する必要があります。ポップアップ型認証の特徴は、画面ビューが特定のしきい値より小さい場合、ポップアップ型認証 GUI が自動的に拡大縮小され、異なる画面サイズに適応することです。例えば、TC-CAPTCHA ポップアップ型モードの初期レンダリングブロックサイズは 360x360 ピクセルです。

JavaScriptベースの認証シナリオ

一部の認証器(例えば、無感覚モードを使用する TC-CAPTCHA)は、JavaScript ランタイム環境として WKWebView インスタンスを必要とし、主に暗号化による作業証明(PoW)チャレンジの実行に使用されます。このシナリオでは、WKWebView インスタンスは JavaScript 実行サンドボックスのみを提供し、UI を可視的にレンダリングする必要はありません。したがって、渡される WKWebView インスタンスは可視である必要はなく、SDK もそれを UI レンダリングに使用しません。

ヘルプとサポート

この記事はお役に立ちましたか?

フィードバック