Esta página foi traduzida pela API Cloud Translation.
Switch to English

Como integrar o reCAPTCHA Enterprise a apps Android

Esta página explica como integrar o reCAPTCHA Enterprise em seu app para Android. Devido à variação em dispositivos móveis em termos de tamanho de tela, desempenho e IUs dos apps, o desafio reCAPTCHA do reCAPTCHA (I m não é um robô) não está disponível para aplicativos de dispositivos móveis. Para ver um método de atrito alternativo, consulte Como configurar a autenticação multifator (MFA, na sigla em inglês).

Antes de começar

  1. Escolha o melhor método para configurar o reCAPTCHA Enterprise em seu ambiente e concluir a configuração.

  2. O SDK do Android pode ser acessado depois da análise de segurança. Entre em contato com nossa equipe de vendas para integrar seu site a esse recurso.

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

  4. Para preparar o ambiente de desenvolvimento, faça o download e instale a versão mais recente do Android Studio.

Como integrar o reCAPTCHA Enterprise ao seu app para Android

Para integrar o reCAPTCHA Enterprise ao seu app para 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 configure 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 de nível de projeto, como 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, adicione a seguinte regra de compilação à seção dependencies do arquivo build.gradle no nível do aplicativo.

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

    Para mais informações sobre 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 app (por exemplo, AndroidManifest.xml). Essa permissão é necessá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 novo projeto, compile o SDK no Android 9.0 ou versão posterior 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 aplicativo (MainActivity.java), invoque a API reCAPTCHA Enterprise chamando os métodos init(), execute() e close() na seguinte sequência:

    1. Chame init() ao iniciar o app ou a atividade que contém a ação que você quer proteger.
    2. Chame execute() depois da ação que você quer proteger. Por exemplo, ao clicar no botão de login. Em seguida, execute() retorna um token RecaptchaResults.
    3. Chame close() quando não houver mais ações para verificar.

    Ao chamar esses três métodos no seu app, modifique 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 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 ...
               }
             }
           });
  }
}

Como processar erros de comunicação

Se seu app não conseguir se comunicar com o serviço reCAPTCHA, talvez seja porque a API encontrou um erro. Adicione uma lógica ao seu app para solucionar esses erros.

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

Referência da API

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

A seguir