이 페이지에서는 Android 앱에 reCAPTCHA Enterprise를 통합하는 방법을 설명합니다. 휴대기기의 화면 크기, 성능, UI 면에서 차이가 있으므로 모바일 앱에서는 시각적인 reCAPTCHA 챌린지(로봇이 아닙니다)를 사용할 수 없습니다. 다른 완화 방법은 다단계 인증(MFA) 구성을 참조하세요.
시작하기 전에
환경에서 reCAPTCHA Enterprise를 설정하는 가장 좋은 방법을 선택하고 설정을 완료합니다.
보안 검토 후 reCAPTCHA Enterprise Android SDK에 액세스할 수 있습니다. 이 기능에 사이트를 온보딩하려면 Google 영업팀에 문의하세요.
Android 앱 플랫폼의 reCAPTCHA 키를 만듭니다.
최신 버전의 Android 스튜디오를 다운로드하고 설치하여 개발 환경을 준비합니다.
Android 앱에 reCAPTCHA Enterprise 통합
Android 앱에 reCAPTCHA Enterprise를 통합하려면 다음 단계를 따르세요.
새 Android 스튜디오 프로젝트를 시작하여 테스트 애플리케이션을 생성합니다. 프로젝트를 만들 때빈 활동 를 선택하고, 언어를 자바로 설정하고, 최소 SDK를API 16: Android 4.1(Jelly Bean)으로 설정합니다.
다음 스니펫과 같이 Google의 Maven 저장소
google()
이 프로젝트 수준build.gradle
파일의 저장소 목록에 있는지 확인합니다.allprojects { repositories { google() } }
자세한 내용은 Google의 Maven 저장소를 참조하세요.
reCAPTCHA Enterprise API 종속 항목을 추가하려면 앱 수준
build.gradle
파일의dependencies
섹션에 다음 빌드 규칙을 추가합니다.implementation 'com.google.android.gms:play-services-recaptcha:17.0.1'
Android 앱의 API 종속 항목에 대한 자세한 내용은 Google Play 서비스 설정을 참조하세요.
애플리케이션 매니페스트에서 첫 번째
<manifest>
태그와 첫 번째<application>
태그 사이에 인터넷 권한을 추가합니다(예:AndroidManifest.xml
). reCAPTCHA Enterprise 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로 마이그레이션을 참조하세요.
앱(
MainActivity.java
)에서 다음 순서대로init()
,execute()
,close()
메서드를 호출하여 reCAPTCHA Enterprise API를 호출합니다.- 앱 또는 보호하려는 작업이 포함된 활동을 시작하면
init()
를 호출합니다. - 보호하려는 조치를 취한 후
execute()
를 호출하세요. 예를 들어 로그인 버튼을 클릭합니다. 이후execute()
는RecaptchaResultData
토큰을 반환합니다. - 확인할 작업이 더 이상 없으면
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 instructions
// 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
를 참조하세요.
다음 단계
- reCAPTCHA 응답 토큰을 평가하려면 평가를 만듭니다.