Obsługa błędów weryfikacji numeru telefonu w Firebase na Androidzie

Gdy wywołanie biblioteki Firebase PNV się nie powiedzie, biblioteka zgłasza błąd FirebasePhoneNumberVerificationException. Na tej stronie znajdziesz listę wszystkich kodów błędów, które mogą być związane z wyjątkiem, wraz z informacjami o tym, kiedy dany błąd występuje i co aplikacja powinna w takiej sytuacji zrobić.

Na tej stronie zakładamy, że masz już zintegrowany pakiet Firebase PNV zgodnie z opisem w artykule Pierwsze kroki z Firebase Phone Number Verification na Androidzie.

Jak są raportowane błędy

• Metody asynchroniczne (getVerificationSupportInfo(), getVerifiedPhoneNumber() i metody niestandardowego procesu) zwracają obiekt Task. Jeśli się nie powiedzie, Task zakończy się błędem FirebasePhoneNumberVerificationException, który otrzymasz w addOnFailureListener.

• enableTestSession() jest synchroniczny. Bezpośrednio wywołuje FirebasePhoneNumberVerificationException.

Aby dowiedzieć się, co poszło nie tak, przeczytaj errorCode wyjątku. Kody Firebase PNV są stałymi w klasie FirebasePnvStatusCodes. Jeśli błąd pochodzi z Usług Google Play, errorCode może też być wartością CommonStatusCodes, np. NETWORK_ERROR.

Nieobsługiwane urządzenie lub karta SIM nie jest błędem. getVerificationSupportInfo() zakończy się powodzeniem i zgłosi isSupported() jako false dla tej karty SIM, a getReason() poda przyczynę. Zobacz Nieobsługiwane urządzenia i karty SIM.

Kody błędów

Konfiguracja sesji testowej

Te błędy są zgłaszane synchronicznie przez enableTestSession().

Weryfikacja

Te błędy powodują niepowodzenie Task zwracanego przez getVerifiedPhoneNumber().

Sprawdzanie pomocy

Task zwracany przez getVerificationSupportInfo() kończy się niepowodzeniem tylko wtedy, gdy nie można uruchomić samej kontroli. W takim przypadku errorCode to wartość Usług Google Play CommonStatusCodes lub CARRIER_NOT_SUPPORTED. Potraktuj urządzenie jako nieobsługiwane i użyj innej metody weryfikacji, np. SMS-a.

Gdy sesja testowa jest włączona, getVerificationSupportInfo() nie kontaktuje się z backendem Firebase PNV i zawsze zgłasza testową kartę SIM jako obsługiwaną, nawet jeśli token testowy wygasł.

Przepływ niestandardowy

Jeśli zamiast getVerifiedPhoneNumber() używasz niestandardowego procesu:

• getDigitalCredentialPayload() kończy się niepowodzeniem z błędem PREFLIGHT_CHECK_FAILED lub INVALID_TEST_NUMBER_ID, jeśli backend odrzuci token testowy.
• exchangeCredentialResponseForPhoneNumber() kończy się niepowodzeniem z błędem INVALID_DIGITAL_CREDENTIAL_RESPONSE lub INVALID_TEST_NUMBER_ID, jeśli backend odrzuci token testowy.
• Twoje wywołanie Credential Manager zwraca błąd GetCredentialException, który obsługujesz bezpośrednio.

Nieobsługiwane urządzenia i karty SIM

Gdy isSupported() ma wartość false dla karty SIM, getReason() zwraca jedną z tych wartości VerificationSupportStatus:

W każdym przypadku użyj innej metody weryfikacji, np. SMS-a, dla tej karty SIM.

Przykład

Poniższy przykład obsługuje błędy, które typowa aplikacja musi rozróżniać podczas wywoływania 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()
        }
    }
}

W tym przykładzie showSmsVerification() to dotychczasowy proces weryfikacji numeru telefonu w aplikacji.

Dalsze kroki

• Szczegółowe informacje o poszczególnych klasach i stałych znajdziesz w dokumentacji interfejsu API Firebase PNV.
• Aby dowiedzieć się, jak zweryfikować token na serwerze, przeczytaj artykuł o weryfikowaniu tokenów Firebase PNV.