reCAPTCHA Enterprise と Android アプリの統合

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

始める前に

  1. ご使用の環境内で reCAPTCHA Enterprise をセットアップするための最適な方法を選択し、セットアップを完了します。

  2. Android SDK には、セキュリティ審査後にアクセスできます。この機能へのサイトのオンボーディングについては、Google の営業チームまでお問い合わせください

  3. Android アプリ プラットフォーム用の reCAPTCHA キーを作成します

  4. Android Studio の最新バージョンをダウンロードおよびインストールし、開発環境を準備します。

reCAPTCHA Enterprise と Android アプリの統合

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

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

  2. 次のスニペットに示すように、Google の Maven リポジトリ google() がプロジェクト レベルの build.gradle ファイル内のリポジトリのリストにあることを確認します。

    allprojects {
        repositories {
            google()
        }
    }
    

    詳しくは、Google の Maven リポジトリをご覧ください。

  3. reCAPTCHA Enterprise API の依存関係を追加するには、アプリレベルの build.gradle ファイルの dependencies セクションに次のビルドルールを追加します。

       implementation 'com.google.android.gms:play-services-recaptcha:16.0.1'
    

    Android アプリでの API 依存関係の詳細については、Google Play 開発者サービスのセットアップをご覧ください。

  4. アプリのマニフェストで、最初の <manifest> タグと最初の <application> タグの間にインターネットの権限を追加します(例: AndroidManifest.xml)。reCAPTCHA Enterprise API にはネットワーク オペレーションが含まれているため、この権限が必要です。

    <manifest ...>
    
        <uses-permission android:name="android.permission.INTERNET" />
    
        <application ...>
        ...
      </application>
    </manifest>
    
  5. 新しいプロジェクトで AndroidX ライブラリを使用する場合は、SDK を Android 9.0 以降にコンパイルし、次のコード スニペットを gradle.properties に追加します。

    android.useAndroidX=true
    android.enableJetifier=true
    

    詳細については、AndroidX への移行をご覧ください。

  6. アプリ(MainActivity.java)で、次の順序で init()execute()close() の各メソッドを呼び出し、reCAPTCHA Enterprise API を起動します。

    1. 保護するアクションを含む、アプリまたはアクティビティを起動するときに init() を呼び出します。
    2. 保護するアクションを実行した後に execute() を呼び出します。たとえば、ログインボタンをクリックします。次に、execute()RecaptchaResultData トークンを返します。
    3. 確認するアクションがなくなったときに close() を呼び出します。

    アプリでこれらの 3 つのメソッドを呼び出すときは、onSuccess() メソッドと onFailure() メソッドをオーバーライドして、API 呼び出しによる両方の可能な結果を処理してください。特に、API が onFailure()ApiException のインスタンスを渡した場合、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 instructions
                   // 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 の応答トークンを評価するため、評価を作成する。