Solicitar a verificação por SMS em um app Android

Para verificar números de telefone automaticamente, é necessário implementar as partes do cliente e do servidor do fluxo de verificação. Este documento descreve como implementar a parte do cliente em um app Android.

Para iniciar o fluxo de verificação de número de telefone em um app Android, envie o número de telefone para o servidor de verificação e chame a API SMS Retriever para começar a detectar uma mensagem SMS com um código único para o app. Depois de receber a mensagem, envie o código de volta ao servidor para concluir o processo de verificação.

Antes de começar

Para preparar o app, siga as etapas nas seções a seguir.

Pré-requisitos do app

O arquivo de build do app precisa usar estes valores:

• Uma minSdkVersion de 19 ou mais recente
• Uma compileSdkVersion de 28 ou mais recente

Configurar o app

No arquivo build.gradle no nível do projeto, inclua o repositório Maven do Google e o repositório central do Maven nas seções buildscript e allprojects:

buildscript {
    repositories {
        google()
        mavenCentral()
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

Adicione a dependência do Google Play Services para a API SMS Retriever ao arquivo de build do Gradle do seu módulo, que geralmente é app/build.gradle:

dependencies {
  implementation 'com.google.android.gms:play-services-auth:21.3.0'
  implementation 'com.google.android.gms:play-services-auth-api-phone:18.1.0'
}

1. Receber o número de telefone do usuário

Você pode conseguir o número de telefone do usuário da maneira que for adequada para seu app. Muitas vezes, a melhor experiência do usuário é usar o seletor de dicas para pedir que o usuário escolha entre os números de telefone armazenados no dispositivo e, assim, evitar digitar um número de telefone manualmente. Para usar o seletor de dicas:

// Construct a request for phone numbers and show the picker
private void requestHint() {
    HintRequest hintRequest = new HintRequest.Builder()
           .setPhoneNumberIdentifierSupported(true)
           .build();

    PendingIntent intent = Auth.CredentialsApi.getHintPickerIntent(
            apiClient, hintRequest);
    startIntentSenderForResult(intent.getIntentSender(),
            RESOLVE_HINT, null, 0, 0, 0);
}

// Obtain the phone number from the result
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == RESOLVE_HINT) {
      if (resultCode == RESULT_OK) {
          Credential credential = data.getParcelableExtra(Credential.EXTRA_KEY);
          // credential.getId();  <-- will need to process phone number string
      }
  }
}

2. Iniciar o recuperador de SMS

Quando estiver tudo pronto para verificar o número de telefone do usuário, receba uma instância do objeto SmsRetrieverClient, chame startSmsRetriever e anexe listeners de sucesso e falha à tarefa de recuperação de SMS:

// Get an instance of SmsRetrieverClient, used to start listening for a matching
// SMS message.
SmsRetrieverClient client = SmsRetriever.getClient(this /* context */);

// Starts SmsRetriever, which waits for ONE matching SMS message until timeout
// (5 minutes). The matching SMS message will be sent via a Broadcast Intent with
// action SmsRetriever#SMS_RETRIEVED_ACTION.
Task<Void> task = client.startSmsRetriever();

// Listen for success/failure of the start Task. If in a background thread, this
// can be made blocking using Tasks.await(task, [timeout]);
task.addOnSuccessListener(new OnSuccessListener<Void>() {
  @Override
  public void onSuccess(Void aVoid) {
    // Successfully started retriever, expect broadcast intent
    // ...
  }
});

task.addOnFailureListener(new OnFailureListener() {
  @Override
  public void onFailure(@NonNull Exception e) {
    // Failed to start retriever, inspect Exception for more details
    // ...
  }
});

A tarefa de recuperação de SMS vai detectar por até cinco minutos uma mensagem SMS que contenha uma string exclusiva que identifica seu app.

3. Enviar o número de telefone para seu servidor

Depois de receber o número de telefone do usuário e começar a receber mensagens SMS, envie o número para o servidor de verificação usando qualquer método (geralmente com uma solicitação POST HTTPS).

Seu servidor gera uma mensagem de verificação e a envia por SMS para o número de telefone especificado. Consulte Realizar a verificação por SMS no servidor.

4. Receber mensagens de verificação

Quando uma mensagem de verificação é recebida no dispositivo do usuário, o Google Play Services transmite explicitamente uma intent SmsRetriever.SMS_RETRIEVED_ACTION para o app, que contém o texto da mensagem. Use um BroadcastReceiver para receber esta mensagem de verificação.

No gerenciador onReceive do BroadcastReceiver, extraia o texto da mensagem de verificação (e, opcionalmente, o endereço do remetente) dos extras da intent:

/**
 * BroadcastReceiver to wait for SMS messages. This can be registered either
 * in the AndroidManifest or at runtime.  Should filter Intents on
 * SmsRetriever.SMS_RETRIEVED_ACTION.
 */
public class MySMSBroadcastReceiver extends BroadcastReceiver {

  @Override
  public void onReceive(Context context, Intent intent) {
    if (SmsRetriever.SMS_RETRIEVED_ACTION.equals(intent.getAction())) {
      Bundle extras = intent.getExtras();
      Status status = (Status) extras.get(SmsRetriever.EXTRA_STATUS);

      switch(status.getStatusCode()) {
        case CommonStatusCodes.SUCCESS:
          // (Optional) Get SMS Sender address - only available in
          // GMS version 24.20 onwards, else it will return null
          String senderAddress = extras.getString(SmsRetriever.EXTRA_SMS_ORIGINATING_ADDRESS);
          // Get SMS message contents
          String message = extras.getString(SmsRetriever.EXTRA_SMS_MESSAGE);
          // Extract one-time code from the message and complete verification
          // by sending the code back to your server.
          break;
        case CommonStatusCodes.TIMEOUT:
          // Waiting for SMS timed out (5 minutes)
          // Handle the error ...
          break;
      }
    }
  }
}

Registre esse BroadcastReceiver com o filtro de intent com.google.android.gms.auth.api.phone.SMS_RETRIEVED (o valor da constante SmsRetriever.SMS_RETRIEVED_ACTION) e a permissão com.google.android.gms.auth.api.phone.permission.SEND (o valor da constante SmsRetriever.SEND_PERMISSION) no arquivo AndroidManifest.xml do app, como no exemplo a seguir, ou use dinamicamente Context.registerReceiver.

<receiver android:name=".MySMSBroadcastReceiver" android:exported="true"
          android:permission="com.google.android.gms.auth.api.phone.permission.SEND">
    <intent-filter>
        <action android:name="com.google.android.gms.auth.api.phone.SMS_RETRIEVED"/>
    </intent-filter>
</receiver>

Importante: é possível detectar que a intent de transmissão é da API SMS Retriever adicionando a permissão com.google.android.gms.auth.api.phone.permission.SEND ao receptor. Essa configuração de permissão está disponível no Google Play Services versão 19.8.31 ou mais recente.

Importante: não adicione a permissão com.google.android.gms.auth.api.phone.permission.SEND ao app. Essa permissão só pode ser usada para detectar a intent da API SMS Retriever no broadcast receiver.

5. Enviar o código único da mensagem de verificação para seu servidor

Agora que você tem o texto da mensagem de verificação, use uma expressão regular ou outra lógica para receber o código único da mensagem. O formato do código único depende de como ele foi implementado no servidor.

Por fim, envie o código único para seu servidor por uma conexão segura. Quando o servidor recebe o código único, ele registra que o número de telefone foi verificado.

Importante: é necessário realizar a verificação do código de uso único no servidor, e não no app cliente.