Gérer les erreurs de vérification du numéro de téléphone Firebase sur Android

En cas d'échec d'un appel à la bibliothèque Firebase PNV, celle-ci renvoie un FirebasePhoneNumberVerificationException. Cette page liste tous les codes d'erreur que l'exception peut contenir, quand chacun d'eux se produit et ce que votre application doit faire.

Cette page suppose que vous avez intégré Firebase PNV comme décrit dans Premiers pas avec Firebase Phone Number Verification sur Android.

Comment les erreurs sont-elles signalées ?

• Les méthodes asynchrones (getVerificationSupportInfo(), getVerifiedPhoneNumber() et les méthodes de flux personnalisé) renvoient un Task. En cas d'échec, l'Task échoue avec un FirebasePhoneNumberVerificationException, que vous recevez dans addOnFailureListener.

• enableTestSession() est synchrone. Elle génère directement une exception FirebasePhoneNumberVerificationException.

Lisez le errorCode de l'exception pour découvrir ce qui s'est mal passé. Les codes Firebase PNV sont des constantes de la classe FirebasePnvStatusCodes. Si l'échec provient des services Google Play, errorCode peut également être une valeur CommonStatusCodes, telle que NETWORK_ERROR.

Un appareil ou une carte SIM non compatibles ne constituent pas une erreur. getVerificationSupportInfo() réussit et indique isSupported() comme false pour cette carte SIM, et getReason() vous indique pourquoi. Consultez Appareils et cartes SIM non compatibles.

Codes d'erreur

Configuration de la session de test

Ces erreurs sont générées de manière synchrone par enableTestSession().

Validation

Ces erreurs entraînent l'échec de l'Task renvoyé par getVerifiedPhoneNumber().

Vérification de la compatibilité

La valeur Task renvoyée par getVerificationSupportInfo() n'échoue que si la vérification elle-même ne peut pas s'exécuter. Dans ce cas, errorCode est une valeur CommonStatusCodes des services Google Play ou CARRIER_NOT_SUPPORTED. Traitez l'appareil comme non compatible et utilisez une autre méthode de validation, comme les SMS.

Lorsqu'une session de test est activée, getVerificationSupportInfo() ne contacte pas le backend Firebase PNV et indique toujours que la carte SIM de test est compatible, même si le jeton de test a expiré.

Flux personnalisé

Si vous utilisez le flux personnalisé au lieu de getVerifiedPhoneNumber() :

• getDigitalCredentialPayload() échoue avec PREFLIGHT_CHECK_FAILED ou avec INVALID_TEST_NUMBER_ID si le backend rejette votre jeton de test.
• exchangeCredentialResponseForPhoneNumber() échoue avec INVALID_DIGITAL_CREDENTIAL_RESPONSE ou avec INVALID_TEST_NUMBER_ID si le backend rejette votre jeton de test.
• Votre propre appel à Credential Manager génère une exception GetCredentialException, que vous gérez directement.

Appareils et cartes SIM non compatibles

Lorsque isSupported() est défini sur false pour une carte SIM, getReason() renvoie l'une des valeurs VerificationSupportStatus suivantes :

Dans chaque cas, utilisez une autre méthode de validation, comme les SMS, pour cette carte SIM.

Exemple

L'exemple suivant gère les erreurs qu'une application type doit distinguer lors de l'appel de 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()
        }
    }
}

Dans cet exemple, showSmsVerification() correspond au flux de validation du numéro de téléphone existant de votre application.

Étapes suivantes

• Pour en savoir plus sur chaque classe et constante, consultez la documentation de référence de l'API Firebase PNV.
• Pour valider le jeton sur votre serveur, consultez Valider les jetons Firebase PNV.