Integrar o reCAPTCHA Enterprise a apps Android

Nesta página, explicamos como integrar o reCAPTCHA Enterprise a apps Android. Devido à variação nos dispositivos móveis em termos de tamanho da tela, desempenho e IUs dos apps, o teste visual do reCAPTCHA (Não sou um robô) não está disponível para apps para dispositivos móveis. Para um método alternativo de atrito, consulte Como configurar a autenticação multifator (MFA).

Antes de começar

  1. Escolha o melhor método para configurar o reCAPTCHA Enterprise no ambiente e conclua a configuração.

  2. O SDK do reCAPTCHA Enterprise para Android pode ser acessado após uma análise de segurança. Entre em contato com nossa equipe de vendas para integrar seu site a esse recurso.

  3. Crie uma chave de reCAPTCHA para a plataforma de app Android.

  4. Prepare seu ambiente de desenvolvimento fazendo o download e instalando a versão mais recente do Android Studio.

Integrar o reCAPTCHA Enterprise ao app Android

Para integrar o reCAPTCHA Enterprise ao seu app Android, faça o seguinte:

  1. Crie um aplicativo de teste iniciando um novo projeto do Android Studio. Ao criar o projeto, selecione Empty Activity, defina a linguagem como Java e defina o SDK mínimo como API 16: Android 4.1 (Jelly Bean).

  2. Verifique se o repositório Maven do Google google() está na lista de repositórios no arquivo build.gradle no nível do projeto, conforme mostrado no snippet a seguir:

    allprojects {
        repositories {
            google()
        }
    }
    

    Para mais informações, consulte Repositório Maven do Google.

  3. Para adicionar a dependência da API reCAPTCHA Enterprise, inclua a seguinte regra de compilação na seção dependencies do arquivo build.gradle no nível do app.

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

    Para saber mais sobre as dependências de API em apps Android, consulte Configurar o Google Play Services.

  4. Adicione permissão de Internet entre a primeira tag <manifest> e a primeira tag <application> no manifesto do aplicativo (por exemplo, AndroidManifest.xml). Essa permissão é obrigatória porque a API reCAPTCHA Enterprise envolve operações de rede.

    <manifest ...>
    
        <uses-permission android:name="android.permission.INTERNET" />
    
        <application ...>
        ...
      </application>
    </manifest>
    
  5. Se você quiser usar bibliotecas AndroidX no seu novo projeto, compile o SDK para o Android 9.0 ou versão mais recente e adicione o seguinte snippet de código ao gradle.properties.

    android.useAndroidX=true
    android.enableJetifier=true
    

    Para mais informações, consulte Como migrar para o AndroidX.

  6. No seu app (MainActivity.java), invoque a API reCAPTCHA Enterprise chamando os métodos init(), execute() e close() na seguinte sequência:

    1. Chame init() quando iniciar o app ou a atividade que contém a ação que você quer proteger.
    2. Chame execute() depois que a ação que você quer proteger for realizada. Por exemplo, quando o botão de login é clicado. Em seguida, execute() retorna um token RecaptchaResultData.
    3. Chame close() quando não houver mais ações a serem verificadas.

    Ao chamar esses três métodos no seu app, substitua os métodos onSuccess() e onFailure() para processar os dois resultados possíveis das chamadas de API. Em especial, se a API transmitir uma instância de ApiException para onFailure(), será necessário gerenciar cada código de status possível que pode ser recuperado usando getStatusCode(). Para ver mais informações, consulte Como processar erros de comunicação.

O snippet de código de amostra a seguir mostra como invocar os métodos init(), execute() e 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 ...
               }
             }
           });
  }
}

Gerenciar erros de comunicação

Se seu app não conseguir se comunicar com o serviço reCAPTCHA, talvez seja porque a API está encontrando um erro. É necessário adicionar lógica ao app para lidar com esses erros.

Para mais detalhes sobre mitigações de erros comuns de API, consulte RecaptchaStatusCodes.

Referência da API

Para uma referência completa da API reCAPTCHA para Android, consulte com.google.android.gms.recaptcha.

A seguir