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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

始める前に

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

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

環境を準備する

  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.0.1'
    

    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 への移行をご覧ください。

reCAPTCHA Enterprise と Android アプリの統合

  1. Android アプリ用に作成した SITE_KEY を使用してクライアントをインスタンス化します。

    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, "YOUR_SITE_KEY")
              .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(), "YOUR_SITE_KEY")
          .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.
    }
    
  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, "YOUR_SITE_KEY")
        .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(), "YOUR_SITE_KEY")
      .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
            }
          });
  }
}

通信エラーを処理する

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

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

API リファレンス

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

次のステップ

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