Gestisci gli errori di verifica del numero di telefono di Firebase su Android

Quando una chiamata alla libreria Firebase PNV non va a buon fine, la libreria segnala un errore FirebasePhoneNumberVerificationException. In questa pagina sono elencati tutti i codici di errore che l'eccezione può contenere, quando si verificano e cosa deve fare la tua app.

Questa pagina presuppone che tu abbia integrato Firebase PNV come descritto in Inizia a utilizzare Firebase Phone Number Verification su Android.

Come vengono segnalati gli errori

• I metodi asincroni (getVerificationSupportInfo(), getVerifiedPhoneNumber() e i metodi del flusso personalizzato) restituiscono un Task. In caso di errore, Task non va a buon fine con un FirebasePhoneNumberVerificationException, che ricevi in addOnFailureListener.

• enableTestSession() è sincrono. Genera direttamente un FirebasePhoneNumberVerificationException.

Leggi il errorCode dell'eccezione per scoprire cosa non ha funzionato. I codici Firebase PNV sono costanti nella classe FirebasePnvStatusCodes. Se l'errore proviene da Google Play Services, errorCode può anche essere un valore CommonStatusCodes, ad esempio NETWORK_ERROR.

Un dispositivo o una SIM non supportati non sono un errore. getVerificationSupportInfo() ha esito positivo e segnala isSupported() come false per la SIM, mentre getReason() ti spiega il motivo. Consulta la sezione Dispositivi e SIM non supportati.

Codici di errore

Configurazione della sessione di test

Questi errori vengono generati in modo sincrono da enableTestSession().

Verifica

Questi errori causano l'esito negativo di Task restituito da getVerifiedPhoneNumber().

Controllo dell'assistenza

L'oggetto Task restituito da getVerificationSupportInfo() non va a buon fine solo se il controllo stesso non può essere eseguito. In questo caso, errorCode è un valore di Google Play Services CommonStatusCodes o CARRIER_NOT_SUPPORTED. Considera il dispositivo come non supportato e utilizza un altro metodo di verifica, ad esempio l'SMS.

Mentre è attiva una sessione di test, getVerificationSupportInfo() non contatta il backend Firebase PNV e segnala sempre la SIM di test come supportata, anche se il token di test è scaduto.

Flusso personalizzato

Se utilizzi il flusso personalizzato anziché getVerifiedPhoneNumber():

• getDigitalCredentialPayload() non va a buon fine con PREFLIGHT_CHECK_FAILED o con INVALID_TEST_NUMBER_ID se il backend rifiuta il token di test.
• exchangeCredentialResponseForPhoneNumber() non riesce con INVALID_DIGITAL_CREDENTIAL_RESPONSE o con INVALID_TEST_NUMBER_ID se il backend rifiuta il token di test.
• La tua chiamata a Gestore delle credenziali genera un'eccezione GetCredentialException, che gestisci direttamente.

Dispositivi e SIM non supportati

Quando isSupported() è false per una SIM, getReason() restituisce uno dei seguenti valori VerificationSupportStatus:

In ogni caso, utilizza un altro metodo di verifica, ad esempio gli SMS, per la SIM.

Esempio

L'esempio seguente gestisce gli errori che una tipica app deve distinguere quando chiama 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()
        }
    }
}

In questo esempio, showSmsVerification() è il flusso di verifica del numero di telefono esistente della tua app.

Passaggi successivi

• Per i dettagli su ogni classe e costante, consulta il Riferimento API Firebase PNV.
• Per verificare il token sul tuo server, consulta Verifica i token Firebase PNV.