reCAPTCHA を Android アプリと統合する

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

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

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

始める前に

reCAPTCHA 用に環境を準備します。
Android アプリプラットフォーム用の reCAPTCHA キーを作成します。

あるいは、次のいずれかの方法で、Android 用の既存の reCAPTCHA キーの ID をコピーできます。
- Google Cloud コンソールから既存のチェックボックスのキーの ID をコピーするには、次の操作を行います。
  1. [reCAPTCHA] ページに移動します。
    
    [reCAPTCHA] に移動
  2. reCAPTCHA キーのリストで、コピーするキーの上にポインタを置き、[] をクリックします。
- REST API を使用して既存のキーの ID をコピーするには、projects.keys.list メソッドを使用します。
- gcloud CLI を使用して既存のキーの ID をコピーするには、gcloud recaptcha keys list コマンドを使用します。

Android 環境を準備する

をご覧ください。

ネイティブ Android

Android Studio の最新バージョンをダウンロードおよびインストールし、開発環境を準備します。
Android SDK の最小値が API 19: Android 4.4（KitKat）に設定されているアプリがあることを確認します。アプリの最小 SDK を API 19 に設定するか、新しいモバイルアプリを作成できます。
新しいモバイルアプリを作成する場合は、新しい Android Studio プロジェクトを開始してテストアプリを作成します。
1. [Empty Activity] を選択します。アプリで Jetpack Compose を使用する場合は、[Empty Compose Activity] を選択します。
2. 言語を kotlin に設定します。
3. SDK の最小値を API 19: Android 4.4（KitKat）に設定します。
次のスニペットに示すように、Google の Maven リポジトリ google() がプロジェクトレベルの build.gradle ファイル内のリポジトリのリストにあることを確認します。
```
allprojects {
    repositories {
        google()
    }
}
```
詳細については、Google の Maven リポジトリをご覧ください。
reCAPTCHA API の依存関係を追加するには、アプリレベルの build.gradle ファイルの dependencies セクションに次のビルドルールを追加します。
```
  implementation 'com.google.android.recaptcha:recaptcha:18.6.1'
```
Android アプリで依存関係を追加する方法については、ビルド依存関係を追加するをご覧ください。
アプリのマニフェストで、最初の <manifest> タグと最初の <application> タグの間にインターネットの権限を追加します（例: AndroidManifest.xml）。reCAPTCHA 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 への移行をご覧ください。

Flutter

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

React Native

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

reCAPTCHA を Android アプリと統合する

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 でブロックしないでください。

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 に移行する方法を示しています。

Kotlin

// 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 ...
    }
  }
}

Java

  // 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 プロパティを使用して指定できます。

Kotlin

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 errors ...
          // See "Handle errors" section
        }
    }

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

Java

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 errors ...
            // See "Handle errors" section
          }
        });

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

エラーを処理する

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

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

API リファレンス

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

次のステップ

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

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

reCAPTCHA を Android アプリと統合する

始める前に

Android 環境を準備する

ネイティブ Android

Flutter

React Native

reCAPTCHA を Android アプリと統合する

fetchClient を使用した Kotlin

fetchClient を使用した Java

Kotlin

Java

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

Kotlin

Java

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

Kotlin

Java

エラーを処理する

API リファレンス

次のステップ

`fetchClient` を使用した Kotlin

`fetchClient` を使用した Java