reCAPTCHA Enterprise と Android アプリの統合

このページでは、reCAPTCHA Enterprise を Android アプリに統合する方法について説明します。画面サイズ、パフォーマンス、アプリの UI に関してモバイルデバイスが多様なため、視覚的な reCAPTCHA チャレンジ（私はロボットではありません）はモバイルアプリではご利用いただけません。別の認証方法については、多要素認証（MFA）の構成をご覧ください。

始める前に

ご使用の環境で reCAPTCHA Enterprise を設定する最適な方法を選択し、設定を完了します。
Android SDK にはセキュリティ審査後にアクセスできます。この機能へのサイトのオンボーディングについては、Google の営業チームまでお問い合わせください。
Android アプリプラットフォームの reCAPTCHA キーを作成します。
Android Studio の最新バージョンをダウンロードしてインストールし、開発環境を準備します。

reCAPTCHA Enterprise と Android アプリの統合

reCAPTCHA Enterprise を Android アプリと統合する手順は次のとおりです。

新しい Android Studio プロジェクトを開始してテストアプリケーションを作成します。プロジェクトの作成時に、[Empty Activity] を選択し、言語を [Java] に設定し、最小 SDK を [API 16: Android 4.1 (Jelly Bean）に設定してください。

注: reCAPTCHA Enterprise は Kotlin をサポートしていません。
次のスニペットに示すように、Google の Maven リポジトリ google() がプロジェクトレベルの build.gradle ファイルのリポジトリリストに含まれていることを確認します。
```
allprojects {
    repositories {
        google()
    }
}
```
詳しくは、Google の Maven リポジトリをご覧ください。
reCAPTCHA Enterprise API の依存関係を追加するには、アプリレベルの build.gradle ファイルの dependencies セクションに次のビルドルールを追加します。
```
   implementation 'com.google.android.gms:play-services-recaptcha:16.0.0'
```
Android アプリでの API の依存関係の詳細については、Google Play 開発者サービスをセットアップするをご覧ください。
アプリのマニフェストで、最初の <manifest> タグと最初の <application> タグの間にインターネットの権限を追加します（例: AndroidManifest.xml）。reCAPTCHA Enterprise API にはネットワークオペレーションが含まれているため、この権限が必要です。
```
<manifest ...>

    <uses-permission android:name="android.permission.INTERNET" />

    <application ...>
    ...
  </application>
</manifest>
```
新しいプロジェクトで AndroidX ライブラリを使用する場合は、SDK を Android 9.0 以降にコンパイルし、次のコードスニペットを gradle.properties に追加します。
```
android.useAndroidX=true
android.enableJetifier=true
```
詳細については、AndroidX への移行をご覧ください。
アプリ（MainActivity.java）で次の順序で init()、execute()、close() メソッドを呼び出し、reCAPTCHA Enterprise API を呼び出します。

注: RecaptchaClient への参照を維持するのではなく、API 呼び出しごとに Recaptcha.getClient(this) を使用してください。
1. 起動するアプリまたはアクティビティを保護するアクティビティの開始時に、init() を呼び出します。
2. 保護するアクションが行われた後に execute() を呼び出します。たとえば、ログインボタンがクリックされます。execute() は RecaptchaResults トークンを返します。
3. 確認するアクションがなくなったときに close() を呼び出します。
アプリでこれらの 3 つのメソッドを呼び出すときは、onSuccess() と onFailure() メソッドをオーバーライドして、API 呼び出しが考えられる結果をすべて処理します。特に、API が ApiException のインスタンスを onFailure() に渡す場合、getStatusCode() を使用して取得できる各ステータスコードを処理する必要があります。詳細については、通信エラーを処理するをご覧ください。

次のサンプルコードは、init()、execute()、close() の各メソッドを呼び出す方法を示しています。

public final class MainActivity extends Activity {
   private RecaptchaHandle handle;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_main);

     // Step 1: Call init() once the activity starts.
     Recaptcha.getClient(this)
         .init("YOUR_SITE_KEY")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaHandle>() {
               @Override
               public void onSuccess(RecaptchaHandle handle) {
                 // Handle success ...
                 MainActivity.this.handle = handle;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

   public void onClick(View v) {
     // Step 2: call execute() when there is an action to protect.
     Recaptcha.getClient(this)
         .execute(this.handle, new RecaptchaAction(new RecaptchaActionType(RecaptchaActionType.LOGIN)))
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaResultData>() {
               @Override
               public void onSuccess(RecaptchaResultData response) {
                 String token = response.getTokenResult();
                 // Handle success ...
                 if (!token.isEmpty()) {
                   Log.d(TAG, "reCAPTCHA response token: " + token);
                   // Validate the response token by following the instruction
                   // when creating an assessment.
                 }
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

  @Override
  protected void onDestroy() {
    // Step 3: call close() when there is no more action to verify.
   Recaptcha.getClient(this)
       .close(handle)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<Boolean>() {
             @Override
             public void onSuccess(Boolean gotClosed) {
               // Handle success ...
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               if (e instanceof ApiException) {
                 ApiException apiException = (ApiException) e;
                 Status apiErrorStatus = apiException.getStatusCode();
                 // Handle api errors ...
               } else {
                 // Handle other failures ...
               }
             }
           });
  }
}

通信エラーの処理

アプリが reCAPTCHA サービスを正常に通信できない場合は、API がエラーを検出した可能性があります。このようなエラーを適切に処理するロジックをアプリに追加する必要があります。

一般的な API エラーの緩和策の詳細については、RecaptchaStatusCodes をご覧ください。

API リファレンス

Android 用 reCAPTCHA API の完全なリファレンスについては、com.google.android.gms.recaptcha をご覧ください。

次のステップ

reCAPTCHA の応答トークンを評価するため、評価を作成する。