reCAPTCHA Enterprise を Android アプリと統合する

このページでは、reCAPTCHA Enterprise を Android アプリに統合する方法について説明します。画面サイズ、パフォーマンス、アプリの UI に関してモバイル デバイスが多様なため、視覚的なチェックボックス reCAPTCHA チャレンジ（私はロボットではありません）はモバイルアプリではご利用いただけません。代わりに、MFA フローなどの独自の階層型適用戦略を実装し、不審なトラフィックに対する代替的な救済パスを提供できます。

重要: この SDK では、リフレクションと動的コードを使用することで、既存のデプロイ済みアプリケーションや SDK で検出システムを変更および改善できます。アプリケーションとの干渉を避けるために、システムで使用できる一連のクラスは管理されたリストに制限されています。

始める前に

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

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

環境を準備する

警告: Android SDK 18.2.0 に移行しないでください。内部エラーのため、アプリが機能しなくなる可能性があります。これらの問題を回避するには、Android SDK 18.2.1 以降に直接移行してください。詳しくは、GitHub の問題レポートをご覧ください。

ネイティブ Android

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

2. Android SDK の最小値が API 19: Android 4.4（KitKat）に設定されているアプリがあることを確認します。アプリの最小 SDK を API 19 に設定するか、新しいモバイルアプリを作成できます。

3. 新しいモバイルアプリを作成する場合は、新しい Android Studio プロジェクトを開始してテスト アプリを作成します。

   1. [Empty Activity] を選択します。アプリで Jetpack Compose を使用する場合は、[Empty Compose Activity] を選択します。
   2. 言語を kotlin に設定します。
   3. 最小 SDK 値を API 19: Android 4.4（KitKat）に設定します。

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

   allprojects {
       repositories {
           google()
       }
   }
   

   詳細については、Google の Maven リポジトリをご覧ください。

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

     implementation 'com.google.android.recaptcha:recaptcha:18.3.0'
   

   Android アプリで依存関係を追加する方法については、ビルド依存関係を追加するをご覧ください。

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

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

7. 新しいプロジェクトで AndroidX ライブラリを使用する場合は、SDK を Android 9.0 以降にコンパイルし、次のコード スニペットを gradle.properties に追加します。

   android.useAndroidX=true
   android.enableJetifier=true
   

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

Flutter

Flutter で reCAPTCHA Enterprise を使用する方法については、Flutter のドキュメントをご覧ください。

ReactNative

React Native を使用した reCAPTCHA Enterprise の使用方法については、React Native のドキュメントをご覧ください。

reCAPTCHA Enterprise と Android アプリの統合

1. Android アプリ用に作成した reCAPTCHA キー（KEY_ID）を使用して、クライアントをインスタンス化します。

   注: reCAPTCHA Enterprise クライアントを使用する必要があるのは、アプリの全期間の内 1 回だけです。

   Kotlin

   class MainActivity : AppCompatActivity() {
   
       private lateinit var recaptchaClient: RecaptchaClient
   
       override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
         initializeRecaptchaClient()
         // ... rest of onCreate code
       }
   
       private fun initializeRecaptchaClient() {
         lifecycleScope.launch {
           Recaptcha.getClient(application, "KEY_ID")
             .onSuccess { client ->
               recaptchaClient = client
             }
             .onFailure { exception ->
               // Handle communication errors ...
               // See "Handle communication errors" section
             }
         }
       }
   
       // ... rest of activity code.
   }
   

   Java

   public final class MainActivity extends Activity {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
       initializeRecaptchaClient();
       // ... rest of onCreate code
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .getTasksClient(getApplication(), "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 MainActivity.this.recaptchaTasksClient = client;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 // Handle communication errors ...
                 // See "Handle communication errors" section
               }
             });
     }
   
     // ... rest of activity code.
   }
   

   注: API が onFailure() に ApiException のインスタンスを渡した場合、getStatusCode() を使用して取得できる各ステータス コードに対応する処理を行う必要があります。詳細については、通信エラーを処理するをご覧ください。

2. reCAPTCHA Enterprise を使用して保護されているアプリのアクションごとに、RecaptchaAction を渡して execute メソッドを呼び出します。reCAPTCHA Enterprise には組み込みのアクションセットが用意されており、必要に応じてカスタムアクションを作成できます。

   次のコード スニペットは、execute を使用して LOGIN アクションを保護する方法を示しています。

   Kotlin

   private fun executeLoginAction() {
     lifecycleScope.launch {
       recaptchaClient
         .execute(RecaptchaAction.LOGIN)
         .onSuccess { token ->
           // Handle success ...
           // See "What's next" section for instructions
           // about handling tokens.
         }
         .onFailure { exception ->
           // Handle communication errors ...
           // See "Handle communication errors" section
         }
     }
   }
   

   Java

   private void executeLoginAction(View v) {
     assert recaptchaTasksClient != null;
     recaptchaTasksClient
       .executeTask(RecaptchaAction.LOGIN)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<String>() {
             @Override
             public void onSuccess(String token) {
               // Handle success ...
               // See "What's next" section for instructions
               // about handling tokens.
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               // Handle communication errors ...
               // See "Handle communication errors" section
             }
           });
   }
   

次のサンプルコード スニペットは、1 つのアクティビティ アプリでの getClient() と execute() メソッドの完全な統合を示しています。

Kotlin

class MainActivity : AppCompatActivity() {

  private lateinit var recaptchaClient: RecaptchaClient

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    initializeRecaptchaClient()
    findViewById<View>(R.id.btn_login).setOnClickListener { executeLoginAction() }
    findViewById<View>(R.id.btn_redeem).setOnClickListener { executeRedeemAction() }
  }

  private fun initializeRecaptchaClient() {
    lifecycleScope.launch {
      Recaptcha.getClient(application, "KEY_ID")
        .onSuccess { client ->
          recaptchaClient = client
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  private fun executeLoginAction() {
    lifecycleScope.launch {
      recaptchaClient
        .execute(RecaptchaAction.LOGIN)
        .onSuccess { token ->
          // Handle success ...
          // See "What's next" section for instructions
          // about handling tokens.
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  private fun executeRedeemAction(){
    lifecycleScope.launch {
      recaptchaClient
        .execute(RecaptchaAction.custom("redeem"))
        .onSuccess { token ->
          // Handle success ...
          // See "What's next" section for instructions
          // about handling tokens.
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }
}

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    findViewById(R.id.btn_login).setOnClickListener(this::executeLoginAction);
    findViewById(R.id.btn_redeem).setOnClickListener(this::executeRedeemAction);
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              MainActivity.this.recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeLoginAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.LOGIN)
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeRedeemAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"))
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  }
}

注意: getClient() と execute() は、デバイス上で完了するまで数秒かかることがあります。そこで、次の手順を行うことをおすすめします。

• アプリの起動時にクライアントを初期化する。たとえば、Application カスタムクラスの onCreate() 呼び出し時などです。
• execute() 呼び出しが UI イベントをブロックしていないことを確認する。アプリに execute() を統合しても、ボタンの押下など、UI イベントをブロックしないでください。たとえば、ビューの作成時に execute() を非同期的に呼び出すことができます。

注: Google Play ストアでは、アプリを Play ストアにアップロードする前に、Google Play のデータ セーフティ フォームに記入する必要があります。データ セーフティ フォームに記入するために reCAPTCHA Enterprise Android SDK についての必要な情報を探すには、Google Play のデータ開示の要件を確認してください。

API 呼び出しのタイムアウトを設定する

getClient API と execute API のタイムアウト値を指定するには、各 API の timeout プロパティを使用します。

getClient API のデフォルトのタイムアウトは 10 秒、execute API のデフォルトのタイムアウトは 5 秒です。

Kotlin

• getClient を呼び出すときのタイムアウトを設定します。

      lifecycleScope.launch {
        Recaptcha.getClient(application, "KEY_ID", timeout = 20000L)
          .onSuccess { client ->
            recaptchaClient = client
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  このコード スニペットでは、getClient のタイムアウトを 20 秒に設定します。

• execute を呼び出すときのタイムアウトを設定します。

      lifecycleScope.launch {
        recaptchaClient
          .execute(RecaptchaAction.LOGIN(), timeout = 10000L)
          .onSuccess { token ->
            // Handle success ...
            // See "What's next" section for instructions
            // about handling tokens.
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  このコード スニペットでは、execute のタイムアウトを 10 秒に設定します。

Java

• getClient を呼び出すときのタイムアウトを設定します。

    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID", 20000L)
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              MainActivity.this.recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  

  このコード スニペットでは、getClient のタイムアウトを 20 秒に設定します。

• execute を呼び出すときのタイムアウトを設定します。

    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"), 10000L)
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  

  このコード スニペットでは、execute のタイムアウトを 10 秒に設定します。

通信エラーを処理する

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

一般的な API エラーの軽減の詳細については、RecaptchaErrorCode をご覧ください。

API リファレンス

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

次のステップ

• reCAPTCHA レスポンストークンを評価するため、評価を作成する。

• 作成した評価の精度に関するフィードバックを提供するため、評価にアノテーションを付ける。

  注: reCAPTCHA レスポンス トークンは、モバイル デバイスからではなく、バックエンド サーバーから評価され、アノテーションが付けられます。