Controla los errores de la verificación del número de teléfono de Firebase en Android

Cuando falla una llamada a la biblioteca de Firebase PNV, la biblioteca informa un FirebasePhoneNumberVerificationException. En esta página, se enumeran todos los códigos de error que puede contener la excepción, cuándo se produce cada uno y qué debe hacer tu app al respecto.

En esta página, se da por sentado que integraste Firebase PNV como se describe en Comienza a usar Firebase Phone Number Verification en Android.

Cómo se informan los errores

• Los métodos asíncronos (getVerificationSupportInfo(), getVerifiedPhoneNumber() y los métodos de flujo personalizado) devuelven un Task. Cuando fallan, el Task falla con un FirebasePhoneNumberVerificationException, que recibes en addOnFailureListener.

• enableTestSession() es síncrono. Arroja un FirebasePhoneNumberVerificationException directamente.

Lee el errorCode de la excepción para averiguar qué salió mal. Los códigos Firebase PNV son constantes en la clase FirebasePnvStatusCodes. Si la falla proviene de los Servicios de Google Play, errorCode también puede ser un valor de CommonStatusCodes, como NETWORK_ERROR.

Un dispositivo o una tarjeta SIM no compatibles no son un error. getVerificationSupportInfo() se ejecuta correctamente y, además, informa isSupported() como false para esa SIM, y getReason() te indica el motivo. Consulta Dispositivos y tarjetas SIM no compatibles.

Códigos de error

Configuración de la sesión de prueba

enableTestSession() arroja estos errores de forma síncrona.

Verificación

Estos errores hacen que falle el objeto Task que devuelve getVerifiedPhoneNumber().

Verificación de compatibilidad

El Task que muestra getVerificationSupportInfo() falla solo si la verificación en sí no se puede ejecutar. En ese caso, errorCode es un valor CommonStatusCodes de los Servicios de Google Play o CARRIER_NOT_SUPPORTED. Trata el dispositivo como no compatible y recurre a otro método de verificación, como SMS.

Mientras una sesión de prueba está habilitada, getVerificationSupportInfo() no se comunica con el backend de Firebase PNV y siempre informa que la SIM de prueba es compatible, incluso si el token de prueba venció.

Flujo personalizado

Si usas el flujo personalizado en lugar de getVerifiedPhoneNumber(), haz lo siguiente:

• getDigitalCredentialPayload() falla con PREFLIGHT_CHECK_FAILED o con INVALID_TEST_NUMBER_ID si el backend rechaza tu token de prueba.
• exchangeCredentialResponseForPhoneNumber() falla con INVALID_DIGITAL_CREDENTIAL_RESPONSE o con INVALID_TEST_NUMBER_ID si el backend rechaza tu token de prueba.
• Tu propia llamada al Administrador de credenciales arroja un GetCredentialException, que controlas directamente.

Dispositivos y tarjetas SIM no compatibles

Cuando isSupported() es false para una SIM, getReason() devuelve uno de los siguientes valores de VerificationSupportStatus:

En cada caso, usa otro método de verificación, como SMS, para esa SIM.

Ejemplo

En el siguiente ejemplo, se controlan los errores que una app típica debe distinguir cuando llama a 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()
        }
    }
}

En este ejemplo, showSmsVerification() es el flujo de verificación del número de teléfono existente de tu app.

Próximos pasos

• Para obtener detalles sobre cada clase y constante, consulta la referencia de la API de Firebase PNV.
• Para verificar el token en tu servidor, consulta Verifica los tokens de Firebase PNV.