Android에서 Firebase 전화번호 인증 오류 처리

Firebase PNV 라이브러리 호출이 실패하면 라이브러리는 FirebasePhoneNumberVerificationException를 보고합니다. 이 페이지에는 예외가 전달할 수 있는 모든 오류 코드, 각 오류 코드가 발생하는 시점, 앱에서 취해야 하는 조치가 나열되어 있습니다.

이 페이지에서는 Android에서 Firebase Phone Number Verification 시작하기에 설명된 대로 Firebase PNV를 통합했다고 가정합니다.

오류 보고 방식

• 비동기 메서드 (getVerificationSupportInfo(), getVerifiedPhoneNumber(), 커스텀 흐름 메서드)는 Task를 반환합니다. 실패하면 Task가 FirebasePhoneNumberVerificationException와 함께 실패하며, 이는 addOnFailureListener에서 수신됩니다.

• enableTestSession()는 동기식입니다. FirebasePhoneNumberVerificationException를 직접 발생시킵니다.

예외의 errorCode를 읽고 무엇이 잘못되었는지 확인합니다. Firebase PNV 코드는 FirebasePnvStatusCodes 클래스의 상수입니다. Google Play 서비스에서 오류가 발생하면 errorCode는 NETWORK_ERROR와 같은 CommonStatusCodes 값이 될 수도 있습니다.

지원되지 않는 기기 또는 SIM은 오류가 아닙니다. getVerificationSupportInfo()가 성공하고 해당 SIM의 isSupported()를 false로 보고하며 getReason()가 이유를 알려줍니다. 지원되지 않는 기기 및 SIM을 참고하세요.

오류 코드

테스트 세션 설정

이러한 오류는 enableTestSession()에 의해 동기식으로 발생합니다.

인증

이러한 오류는 getVerifiedPhoneNumber()에서 반환한 Task를 실패하게 합니다.

지원 확인

getVerificationSupportInfo()에서 반환된 Task은 검사 자체를 실행할 수 없는 경우에만 실패합니다. 이 경우 errorCode는 Google Play 서비스 CommonStatusCodes 값 또는 CARRIER_NOT_SUPPORTED입니다. 기기를 지원되지 않는 것으로 처리하고 SMS와 같은 다른 확인 방법으로 대체합니다.

테스트 세션이 사용 설정되어 있는 동안에는 getVerificationSupportInfo()가 Firebase PNV 백엔드에 연결하지 않으며 테스트 토큰이 만료된 경우에도 항상 테스트 SIM을 지원되는 것으로 보고합니다.

커스텀 흐름

getVerifiedPhoneNumber() 대신 맞춤 흐름을 사용하는 경우:

• getDigitalCredentialPayload()는 PREFLIGHT_CHECK_FAILED로 실패하거나 백엔드가 테스트 토큰을 거부하는 경우 INVALID_TEST_NUMBER_ID로 실패합니다.
• exchangeCredentialResponseForPhoneNumber()는 INVALID_DIGITAL_CREDENTIAL_RESPONSE와 함께 실패하거나 백엔드가 테스트 토큰을 거부하는 경우 INVALID_TEST_NUMBER_ID와 함께 실패합니다.
• 인증 관리자에 대한 자체 호출에서 GetCredentialException가 발생하며, 이를 직접 처리합니다.

지원되지 않는 기기 및 SIM

SIM의 isSupported()가 false인 경우 getReason()는 다음 VerificationSupportStatus 값 중 하나를 반환합니다.

각 경우에 해당 SIM에 SMS와 같은 다른 확인 방법을 사용하세요.

예

다음 예에서는 일반적인 앱이 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()
        }
    }
}

이 예시에서 showSmsVerification()는 앱의 기존 전화번호 인증 흐름입니다.

다음 단계

• 각 클래스 및 상수에 관한 자세한 내용은 Firebase PNV API 참조를 확인하세요.
• 서버에서 토큰을 확인하려면 Firebase PNV 토큰 확인을 참고하세요.