Android 앱에 reCAPTCHA Enterprise 통합

이 페이지에서는 Android 앱에 reCAPTCHA Enterprise를 통합하는 방법을 설명합니다. 휴대기기의 화면 크기, 성능, UI 면에서 차이가 있으므로 모바일 앱에서는 시각적인 reCAPTCHA 챌린지(로봇이 아닙니다)를 사용할 수 없습니다. 다른 완화 방법은 다단계 인증(MFA) 구성을 참조하세요.

시작하기 전에

  1. 환경에서 reCAPTCHA Enterprise를 설정하는 가장 좋은 방법을 선택하고 설정을 완료합니다.

  2. Android SDK는 보안 검토 후 액세스할 수 있습니다. 이 기능에 사이트를 온보딩하려면 Google 영업팀에 문의하세요.

  3. Android 앱 플랫폼의 reCAPTCHA 키를 만듭니다.

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

Android 앱에 reCAPTCHA Enterprise 통합

Android 앱에 reCAPTCHA Enterprise를 통합하려면 다음 단계를 따르세요.

  1. 새 Android 스튜디오 프로젝트를 시작하여 테스트 애플리케이션을 생성합니다. 프로젝트를 만들 때빈 활동 를 선택하고, 언어를 자바로 설정하고, 최소 SDK를API 16: Android 4.1(Jelly Bean)으로 설정합니다.

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

    allprojects {
    repositories {
        google()
    }
}

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

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

       implementation 'com.google.android.gms:play-services-recaptcha:16.0.0'

    Android 앱의 API 종속 항목에 대한 자세한 내용은 Google Play 서비스 설정을 참조하세요.

  4. 애플리케이션 매니페스트에서 첫 번째 <manifest> 태그와 첫 번째 <application> 태그 사이에 인터넷 권한을 추가합니다(예: AndroidManifest.xml). reCAPTCHA Enterprise API를 사용하려면 네트워크 작업이 필요하므로 이 권한이 필요합니다.

    <manifest ...>

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

    <application ...>
    ...
  </application>
</manifest>

  5. 새 프로젝트에서 AndroidX 라이브러리를 사용하려면 SDK를 Android 9.0 이상으로 컴파일하고 다음 코드 스니펫을 gradle.properties에 추가하세요.

    android.useAndroidX=true
android.enableJetifier=true

    자세한 내용은 AndroidX로 마이그레이션을 참조하세요.

  6. 앱(MainActivity.java)에서 다음 순서대로 init(), execute(), close() 메서드를 호출하여 reCAPTCHA Enterprise API를 호출합니다.

    1. 앱 또는 보호하려는 작업이 포함된 활동을 시작하면 init()를 호출합니다.
    2. 보호하려는 조치를 취한 후 execute()를 호출하세요. 예를 들어 로그인 버튼을 클릭합니다. 이후 execute()는 RecaptchaResults 토큰을 반환합니다.
    3. 확인할 작업이 더 이상 없으면 close()를 호출합니다.

    앱에서 세 가지 메서드를 호출할 때 API 호출의 가능한 결과를 모두 처리하려면 onSuccess() 및 onFailure() 메서드를 재정의합니다. 특히 API가 ApiException의 인스턴스를 onFailure()로 전달하는 경우 getStatusCode()를 사용하여 검색할 수 있는 가능한 상태 코드를 모두 처리해야 합니다. 자세한 내용은 통신 오류 처리하기를 참고하세요.

다음 샘플 코드 스니펫은 init(), execute(), close() 메서드를 호출하는 방법을 보여줍니다.

public final class MainActivity extends Activity {
   private RecaptchaHandle handle;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_main);

     // Step 1: Call init() once the activity starts.
     Recaptcha.getClient(this)
         .init("YOUR_SITE_KEY")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaHandle>() {
               @Override
               public void onSuccess(RecaptchaHandle handle) {
                 // Handle success ...
                 MainActivity.this.handle = handle;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

   public void onClick(View v) {
     // Step 2: call execute() when there is an action to protect.
     Recaptcha.getClient(this)
         .execute(this.handle, new RecaptchaAction(new RecaptchaActionType(RecaptchaActionType.LOGIN)))
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaResultData>() {
               @Override
               public void onSuccess(RecaptchaResultData response) {
                 String token = response.getTokenResult();
                 // Handle success ...
                 if (!token.isEmpty()) {
                   Log.d(TAG, "reCAPTCHA response token: " + token);
                   // Validate the response token by following the instruction
                   // when creating an assessment.
                 }
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

  @Override
  protected void onDestroy() {
    // Step 3: call close() when there is no more action to verify.
   Recaptcha.getClient(this)
       .close(handle)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<Boolean>() {
             @Override
             public void onSuccess(Boolean gotClosed) {
               // Handle success ...
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               if (e instanceof ApiException) {
                 ApiException apiException = (ApiException) e;
                 Status apiErrorStatus = apiException.getStatusCode();
                 // Handle api errors ...
               } else {
                 // Handle other failures ...
               }
             }
           });
  }
}

통신 오류 처리

앱이 reCAPTCHA 서비스와 성공적으로 통신할 수 없으면 API에 오류가 발생한 것일 수 있습니다. 이러한 오류를 정상적으로 처리하는 로직을 앱에 추가해야 합니다.

일반적인 API 오류의 완화에 대한 자세한 내용은 RecaptchaStatusCodes를 참조하세요.

API 참조

Android용 reCAPTCHA API의 전체 참조는 com.google.android.gms.recaptcha를 참조하세요.

다음 단계