reCAPTCHA を Android アプリと統合する

このページでは、Android アプリに reCAPTCHA を統合する方法について説明します。

不審なトラフィックに対して視覚的な問題チャレンジを提供する場合は、SafetyNet reCAPTCHA API を使用できます。

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

始める前に

1. reCAPTCHA 用に環境を準備します。

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

   あるいは、次のいずれかの方法で、Android 用の既存の reCAPTCHA キーの ID をコピーできます。

   • Google Cloud コンソールから既存のチェックボックスのキーの ID をコピーするには、次の操作を行います。

     1. [reCAPTCHA] ページに移動します。

        [reCAPTCHA] に移動

     2. reCAPTCHA キーのリストで、コピーするキーの上にポインタを置き、[ content_copy ] をクリックします。
   • REST API を使用して既存のキーの ID をコピーするには、projects.keys.list メソッドを使用します。
   • gcloud CLI を使用して既存のキーの ID をコピーするには、gcloud recaptcha keys list コマンドを使用します。

Android 環境を準備する

reCAPTCHA を Android アプリと統合する

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

   fetchClient を使用した Kotlin

   fetchClient メソッドはクライアントをすぐに返して、バックグラウンドで SDK の初期化を開始します。ネットワーク障害が発生した場合、reCAPTCHA サーバーとの通信を再試行します。

   class CustomApplication : Application() {
   
       private lateinit var recaptchaClient: RecaptchaClient
   
       override fun onCreate() {
         super.onCreate()
         initializeRecaptchaClient()
       }
   
       private fun initializeRecaptchaClient() {
         lifecycleScope.launch {
           try {
             recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
           } catch(e: RecaptchaException) {
             // Handle errors ...
             // See "Handle errors" section
           }
         }
       }
   }
   

   fetchClient を使用した Java

   public final class CustomApplication extends Application {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     protected void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(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 errors ...
                 // See "Handle errors" section
               }
             });
     }
   }
   

   SDK の初期化が完了するまでに数秒かかることがあります。このレイテンシを軽減するには、カスタム Application クラスの onCreate() 呼び出し時など、できるだけ早くクライアントを初期化します。UI 要素を reCAPTCHA SDK でブロックしないでください。

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

   次のコード スニペットは、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 errors ...
         }
     }
   }
   

   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 errors ...
             }
           });
   }
   

getClient メソッドから fetchClient メソッドに移行する

fetchClient メソッドは、ネットワーク障害が発生した場合に初期化を再試行する RecaptchaClient を返します。クライアントの作成時にアプリがネットワークにアクセスできない場合、クライアントは再試行を続け、ネットワークが取得されると正常に初期化されます。

execute(timeout) を呼び出したときにクライアントの準備ができていない場合は、トークンまたは RecaptchaErrorCode を返す前に初期化を試みます。

次の例は、getClient から fetchClient に移行する方法を示しています。

// Migrate from getClient
private fun initializeWithGetClient() {
  lifecycleScope.launch {
    Recaptcha.getClient(application, "KEY_ID")
      .onSuccess { client ->
        recaptchaClient = client
      }
      .onFailure { exception ->
        // Handle errors ...
      }
  }
}

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  lifecycleScope.launch {
    try {
      recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
    } catch(e: RecaptchaException){
      // Handle errors ...
    }
  }
}

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

  // Migrate to fetchTaskClient
  private void initializeWithFetchTaskClient() {
    Recaptcha
      .fetchTaskClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

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

execute API のタイムアウト値は、withTimeout プロパティを使用して指定できます。

エラーを処理する

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

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

API リファレンス

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

次のステップ

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