Processar erros da verificação de número de telefone do Firebase no Android

Quando uma chamada para a biblioteca Firebase PNV falha, ela informa um FirebasePhoneNumberVerificationException. Nesta página, listamos todos os códigos do erro que a exceção pode conter, quando cada um ocorre e o que seu app precisa fazer a respeito.

Nesta página, presumimos que você tenha integrado o Firebase PNV conforme descrito em Começar a usar o Firebase Phone Number Verification no Android.

Como os erros são informados

• Os métodos assíncronos (getVerificationSupportInfo(), getVerifiedPhoneNumber() e os métodos de fluxo personalizado) retornam um Task. Quando elas falham, o Task falha com um FirebasePhoneNumberVerificationException, que você recebe em addOnFailureListener.

• enableTestSession() é síncrono. Ele gera um FirebasePhoneNumberVerificationException diretamente.

Leia o errorCode da exceção para descobrir o que deu errado. Os códigos Firebase PNV são constantes na classe FirebasePnvStatusCodes. Se a falha for do Google Play Services, errorCode também pode ser um valor CommonStatusCodes, como NETWORK_ERROR.

Um dispositivo ou chip incompatível não é um erro. getVerificationSupportInfo() for bem-sucedido e informar isSupported() como false para esse chip, e getReason() informar o motivo. Consulte Dispositivos e chips incompatíveis.

Códigos de erro

Configuração da sessão de teste

Esses erros são gerados de forma síncrona por enableTestSession().

Verificação

Esses erros causam falha no Task retornado por getVerifiedPhoneNumber().

Verificação de suporte

O Task retornado por getVerificationSupportInfo() falhará apenas se a verificação em si não puder ser executada. Nesse caso, errorCode é um valor CommonStatusCodes do Google Play Services ou CARRIER_NOT_SUPPORTED. Trate o dispositivo como não compatível e use outro método de verificação, como SMS.

Enquanto uma sessão de teste está ativada, o getVerificationSupportInfo() não entra em contato com o back-end do Firebase PNV e sempre informa o chip de teste como compatível, mesmo que o token de teste tenha expirado.

Fluxo personalizado

Se você usar o fluxo personalizado em vez de getVerifiedPhoneNumber():

• getDigitalCredentialPayload() falha com PREFLIGHT_CHECK_FAILED ou com INVALID_TEST_NUMBER_ID se o back-end rejeitar o token de teste.
• exchangeCredentialResponseForPhoneNumber() falha com INVALID_DIGITAL_CREDENTIAL_RESPONSE ou com INVALID_TEST_NUMBER_ID se o back-end rejeitar o token de teste.
• Sua própria chamada para o Credential Manager gera um GetCredentialException, que você processa diretamente.

Dispositivos e chips incompatíveis

Quando isSupported() é false para um chip, getReason() retorna um dos seguintes valores VerificationSupportStatus:

Em cada caso, use outro método de verificação, como SMS, para esse chip.

Exemplo

O exemplo a seguir processa os erros que um app típico precisa distinguir ao chamar getVerifiedPhoneNumber():

import android.util.Log
// Credential Manager is included with the Firebase PNV library.
import androidx.credentials.exceptions.GetCredentialCancellationException
import com.google.firebase.pnv.FirebasePhoneNumberVerification
import com.google.firebase.pnv.FirebasePhoneNumberVerificationException
import com.google.firebase.pnv.FirebasePnvStatusCodes

private const val TAG = "PhoneVerification"

// In your Activity:
private fun verifyPhoneNumber() {
    FirebasePhoneNumberVerification.getInstance()
        .getVerifiedPhoneNumber(this)
        .addOnSuccessListener { result ->
            // Send result.getToken() to your backend.
        }
        .addOnFailureListener { e -> handleFpnvError(e) }
}

private fun handleFpnvError(e: Exception) {
    if (e !is FirebasePhoneNumberVerificationException) {
        Log.w(TAG, "Firebase PNV failed", e)
        showSmsVerification()
        return
    }
    when (e.errorCode) {
        FirebasePnvStatusCodes.CREDENTIAL_MANAGER_ERROR -> {
            if (e.cause is GetCredentialCancellationException) {
                // The user dismissed the consent screen.
            }
            showSmsVerification()
        }
        FirebasePnvStatusCodes.INVALID_TEST_NUMBER_ID -> {
            // Test mode only: generate a new test token.
            Log.e(TAG, "Firebase PNV test token rejected", e)
        }
        FirebasePnvStatusCodes.ACTIVITY_CONTEXT_REQUIRED -> {
            // App bug: pass an Activity to getVerifiedPhoneNumber().
            Log.e(TAG, "Firebase PNV needs an Activity context", e)
        }
        else -> {
            // Carrier not supported, network errors, and other failures.
            Log.w(TAG, "Firebase PNV failed with error code ${e.errorCode}", e)
            showSmsVerification()
        }
    }
}

Neste exemplo, showSmsVerification() é o fluxo de verificação de número de telefone do seu app.

Próximas etapas

• Para detalhes sobre cada classe e constante, consulte a referência da API Firebase PNV.
• Para verificar o token no servidor, consulte Verificar tokens do Firebase PNV.