Android 앱에 reCAPTCHA 통합

이 페이지에서는 Android 앱에 reCAPTCHA를 통합하는 방법을 설명합니다.

의심스러운 트래픽에 시각적 챌린지를 제공하려면 SafetyNet reCAPTCHA API를 사용하면 됩니다.

SDK는 리플렉션 및 동적 코드를 사용하여 기존 배포 애플리케이션/SDK의 감지 시스템을 수정하고 조정할 수 있습니다. 시스템에서 사용할 수 있는 클래스 세트는 애플리케이션에 대한 간섭을 방지하기 위해 제어된 목록으로 제한됩니다.

중요: 지원 중단 및 종료 정책을 숙지하고 정기적으로 SDK를 업그레이드할 계획을 세우세요.

시작하기 전에

1. reCAPTCHA 환경을 준비합니다.

2. 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 SDK 18.2.0으로 마이그레이션하지 마세요. 내부 오류로 인해 앱이 작동하지 않을 수 있습니다. 이러한 문제를 방지하려면 Android SDK 18.2.1 이상으로 직접 마이그레이션하기 바랍니다. 자세한 내용은 GitHub의 문제 보고서를 참조하세요.

기본 Android

1. 최신 버전의 Android 스튜디오를 다운로드하고 설치하여 개발 환경을 준비합니다.

2. 최소 Android SDK 값이 API 23: Android 6.0(Espresso)로 설정된 앱이 있는지 확인합니다. 앱의 최소 SDK를 API 19로 설정하거나 새 모바일 앱을 만들 수 있습니다.

3. 새 모바일 앱을 만드는 경우 새로운 Android 스튜디오 프로젝트를 시작하여 테스트 애플리케이션을 만듭니다.

   1. 빈 활동을 선택합니다. 앱에서 Jetpack Compose를 사용하려면 빈 Compose 활동을 선택합니다.
   2. 언어를 kotlin으로 설정합니다.
   3. 최소 SDK 값을 API 23: Android 6.0(Espresso)로 설정합니다.

4. 다음 스니펫과 같이 Google의 Maven 저장소 google()이 프로젝트 수준 build.gradle 파일의 저장소 목록에 있는지 확인합니다.

   allprojects {
       repositories {
           google()
       }
   }
   

   자세한 내용은 Google의 Maven 저장소를 참조하세요.

5. reCAPTCHA API 종속 항목을 추가하려면 앱 수준 build.gradle 파일의 dependencies 섹션에 다음 빌드 규칙을 추가합니다.

     implementation 'com.google.android.recaptcha:recaptcha:18.7.0-beta01'
   

   Android 앱에 종속 항목을 추가하는 방법에 대한 자세한 내용은 빌드 종속 항목 추가를 참조하세요.

6. 애플리케이션 매니페스트에서 첫 번째 <manifest> 태그와 첫 번째 <application> 태그 사이에 인터넷 권한을 추가합니다(예: AndroidManifest.xml). reCAPTCHA 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를 사용하는 방법에 대한 자세한 내용은 Flutter 문서를 참조하세요.

React Native

React Native를 통해 reCAPTCHA를 사용하는 방법에 대한 자세한 내용은 React Native 문서를 참조하세요.

Android 앱에 reCAPTCHA 통합

1. Android 앱용으로 만든 reCAPTCHA 키(KEY_ID)를 사용하여 클라이언트를 인스턴스화합니다.

   참고: reCAPTCHA 클라이언트는 앱 수명 동안 한 번만 사용해야 합니다.

   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() 호출 중에 클라이언트를 최대한 일찍 초기화하세요. reCAPTCHA SDK에서 UI 요소를 차단해서는 안 됩니다.

   참고: 특히 API가 ApiException의 인스턴스를 onFailure()로 전달하는 경우 getStatusCode()를 사용하여 검색할 수 있는 각 가능한 상태 코드를 처리해야 합니다. 자세한 내용은 오류 처리를 참조하세요.

2. reCAPTCHA를 사용하여 보호되는 앱의 각 작업에 대해 execute 메서드를 호출하여 RecaptchaAction을 전달합니다. 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 ...
         }
     }
   }
   

   자바

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

참고: Google Play 스토어에서 앱을 Play 스토어에 업로드하기 전에 Google Play의 데이터 보안 양식을 작성해야 합니다. Google Play의 데이터 공개 요건을 검토하여 reCAPTCHA Android SDK에 대해 필요한 정보를 확인하고 데이터 보안 양식을 작성하세요.

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

자바

  // 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 호출 제한 시간 설정

withTimeout 속성을 사용하여 execute API에 대한 제한 시간 값을 지정할 수 있습니다.

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초로 설정합니다.

자바

• 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 응답 토큰은 휴대기기가 아닌 백엔드 서버에서 평가 및 주석 처리됩니다.