tencent cloud

Tencent Cloud EdgeOne

Androidの統合手順

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

概要

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

統合手順

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

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

EdgeOne クライアント認証 SDK を Android プロジェクトに統合することが最初のステップです。Maven を通じて SDK を導入できます。お使いの setting.gradle またはプロジェクトの build.gradle に Maven リポジトリを追加します:
// setting.gradle またはプロジェクトの build.gradle
repositories {
// 以下の maven 設定を追加します。
maven { url 'https://repo.maven.com/' } // サンプルMavenリポジトリです。実際のSDKが提供するMavenリポジトリに置き換えてください。
}
お使いのアプリケーションモジュールの build.gradle に依存関係を追加します:
// app/build.gradle
dependencies {
implementation 'com.tencent.cloud:clientattestation:latest.release'
}

2. AndroidManifest.xmlの権限を設定する

SDK は認証プロセスを実行する際に、基本的なネットワークアクセス権限が必要です。SDK が正常にネットワーク通信を行えるように、プロジェクトの AndroidManifest.xml ファイルに以下の権限宣言を追加してください:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
また、SDK 内部の一部のネイティブライブラリをサポートするために、サポートする CPU アーキテクチャを設定する必要がある場合があります。app/build.gradle の defaultConfig に以下を追加します:
android {
defaultConfig {
ndk {
abiFilters "armeabi-v7a", "arm64-v8a" // 選択可能:armeabi-v7a または arm64-v8a
}
}
}
プロジェクトで ProGuard を使用してコード難読化を行っている場合は、ProGuard 設定ファイル(通常は proguard-rules.pro)に以下の難読化ルールを追加して、SDK 内部クラスが難読化されないようにしてください:
-keep class com.**.TNative$aa { public *; }
-keep class com.**.TNative$aa$bb { public *; }
-keep class com.**.TNative$bb { *; }
-keep class com.**.TNative$bb$I { *; }
-keep class com.tcbas.**{*;}

3. SDKを初期化する

認証機能を使用する前に、お客様のサービスドメインと任意のログレベルを使用して EdgeOne SDK を初期化する必要があります。この操作は通常、お客様の Application クラスまたはアプリケーション起動時に一度実行されます。
import com.tcbas.common.framework.TCBas;
import com.tcbas.common.framework.TCBasConfig;

public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
// SDK初期化
String baseUrl = "www.example.com"; // 業務ドメインに設定します。
TCBas.init(getApplicationContext(), new TCBasConfig.Builder().baseUrl(baseUrl).build());

// 任意:ログレベルを設定します。
// TCBas.init(getApplicationContext(), new TCBasConfig.Builder()
// .baseUrl(baseUrl)
// .logLevel(LOG_LEVEL_DEBUG) // 任意:ログレベルを設定します。
// .build());
// 任意:AndroidIdを設定します。
// TCBas.init(getApplicationContext(), new TCBasConfig.Builder()
// .baseUrl(baseUrl)
// .logLevel(LOG_LEVEL_DEBUG) // 任意:ログレベルを設定します。
// .extraDataProvider(new ExtraDataProvider(){
// @Override
// public String getAndroidId() {
// return super.getAndroidId();
// }
// })
// .build());

}
}
パラメータの説明:
baseUrl:お客様の EdgeOne サービスドメインです。例:www.example.com。
extraDataProvider:任意パラメータです。AndroidIdを提供し、リスク識別能力を向上させます。
logLevel:任意パラメータです。SDKのログ出力レベルを制御するために使用されます。選択可能な値は以下の通りです:
LOG_LEVEL_NONE:ログを無効にします(デフォルト)。
LOG_LEVEL_DEBUG:debug以上のレベルのログを有効にします。
LOG_LEVEL_INFO:info以上のレベルのログを有効にします。
LOG_LEVEL_WARN:warning以上のレベルのログを有効にします。
LOG_LEVEL_ERROR:error以上のレベルのログを有効にします。

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

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

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

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

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

// attestId
// 主動的にチャレンジを開始する際にコンソールから取得します。
// 受動的にチャレンジが開始された際に、httpが返すheaderフィールド内の「EO-Attest-Challenge」から取得します。
String attestId = "your-attestId";
AttestParams params = new AttestParams.Builder()
.attestId(attestId)
.webView(yourWebViewInstance) // Captcha画面の表示に使用するWebViewです。Captchaが不要な場合は、このパラメータを設定する必要はありません。
.reqTimeoutMillis(60000) // オプション、リクエストタイムアウト時間、単位:ミリ秒、デフォルト60秒
.build();

ClientAttestation.getInstance().attestWithParams(params, new AttestCallback() {
@Override
public void onSuccess(String token) {
// リスクチケットを返し、チケットをhttpリクエストのheaderフィールド「EO-Attest-Token」に配置します。
// 例えば:ここで以前失敗したリクエストを再送し、新しいトークンを付与できます。
}

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

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

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

// 例:トークンをネットワークリクエストヘッダーに追加します。
// OkHttp または他のネットワークライブラリを使用していると仮定します。
if (attestToken != null) {
// OkHttp の例
// Request originalRequest = new Request.Builder()
// .url("https://your-backend-api.com/data")
// .build();
// Request.Builder requestBuilder = originalRequest.newBuilder();
// requestBuilder.header("EO-Attest-Token", attestToken);
// Request request = requestBuilder.build();
// // 引き続きリクエストを送信します。
}
重要なお知らせ: 認証が必要なすべてのAPIリクエストにこのトークンを含めてください。SDKがトークンのライフサイクルを自動的に管理するため、リクエストを送信する前に最新のトークンを取得するだけで済みます。

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

お客様のバックエンドサービス(EdgeOne によって保護されている)がクライアントリクエストを受信すると、リクエストに有効な認証トークンが含まれているかどうかを確認します。リクエストに認証が必要であるにもかかわらず有効なトークンが含まれていない場合、サーバーは HTTP 428 ステータスコードを返し、クライアントに追加認証が必要であることを示します。これは、Android クライアント統合において開発者が能動的に対応する必要がある重要なポイントです。
お客様のAndroidアプリは、これらのHTTP 428レスポンスをキャプチャして処理するメカニズムを実装する必要があります。具体的な処理フローについては、認証トークンの再取得、または期限切れ認証トークンの更新(HTTP 428チャレンジの処理)を参照してください。
以下は、428チャレンジを処理する簡略化された例です(OkHttpを例とします):
import okhttp3.Call;
import okhttp3.Callback;
import okhttp3.Headers;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
import android.webkit.WebView;
import com.tc.eo.clientattestation.ClientAttestation;
import com.tc.eo.clientattestation.AttestCallback;
import com.tc.eo.clientattestation.AttestParams;

public class ApiClient {

private OkHttpClient client = new OkHttpClient();
private WebView webViewInstance; // WebViewインスタンスがあると仮定します。

public ApiClient(WebView webView) {
this.webViewInstance = webView;
}

public void makeProtectedRequest(String url) {
Request request = new Request.Builder()
.url(url)
.header("EO-Attest-Token", ClientAttestation.getInstance().getAttestationToken())
.build();

client.newCall(request).enqueue(new Callback() {
@Override
public void onFailure(Call call, IOException e) {
// ネットワークリクエストの失敗を処理します。
e.printStackTrace();
}

@Override
public void onResponse(Call call, Response response) throws IOException {
if (response.code() == 428) {
Headers headers = response.headers();
String challengeId = headers.get("EO-Attest-Challenge");
if (challengeId != null) {
// 428チャレンジを受信したら、認証を実行します。
AttestParams params = new AttestParams.Builder()
.attestId(challengeId)
.webView(webViewInstance) // WebViewインスタンスを渡します。
.build();

ClientAttestation.getInstance().attestWithParams(params, new AttestCallback() {
@Override
public void onSuccess(String token) {
// 認証が成功したため、リクエストを再送信します。
makeProtectedRequest(url); // 元のリクエストを再発行します。
}

@Override
public void onError(int errorCode, String msg) {
// 認証に失敗しました。
System.err.println("認証失敗: " + msg);
}
});
} else {
System.err.println("428 レスポンスに EO-Attest-Challenge ヘッダーが見つかりません");
}
} else if (response.isSuccessful()) {
// リクエストが成功し、ビジネスデータを処理します。
System.out.println("リクエスト成功: " + response.body().string());
} else {
// その他のHTTPエラーを処理します。
System.err.println("リクエスト失敗: " + response.code() + " " + response.message());
}
}
});
}
}

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

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

対話型認証シナリオ

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

JavaScriptベースの認証シナリオ

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

ヘルプとサポート

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

フィードバック