איך לטפל בשגיאות ב-Phone Number Verification ב-Firebase ב-Android

אם קריאה לספרייה Firebase PNV נכשלת, הספרייה מדווחת על FirebasePhoneNumberVerificationException. בדף הזה מפורטים כל קודי השגיאה שהחריגה יכולה להכיל, מתי כל אחד מהם מתרחש ומה האפליקציה צריכה לעשות בקשר לזה.

ההנחה היא שכבר שילבתם את Firebase PNV כמו שמתואר במאמר תחילת העבודה עם Firebase Phone Number Verification ב-Android.

איך מתבצע הדיווח על שגיאות

  • שיטות אסינכרוניות (getVerificationSupportInfo(), getVerifiedPhoneNumber() והשיטות של תהליך בהתאמה אישית) מחזירות Task. כשהן נכשלות, ה-Task נכשל עם FirebasePhoneNumberVerificationException, שמתקבל ב-addOnFailureListener.

  • ‫enableTestSession() היא סינכרונית. היא זורקת FirebasePhoneNumberVerificationException ישירות.

קוראים את ה-errorCode של החריגה כדי להבין מה השתבש. הקודים של Firebase PNV הם קבועים במחלקה FirebasePnvStatusCodes. אם הכשל נובע מ-Google Play Services, הערך של errorCode יכול להיות גם CommonStatusCodes, למשל NETWORK_ERROR.

מכשיר או כרטיס SIM לא נתמכים הם לא שגיאה. getVerificationSupportInfo() מצליח ומדווח על isSupported() בתור false עבור אותו SIM, ו-getReason() מסביר למה. מידע נוסף על מכשירים וכרטיסי SIM לא נתמכים

קודי שגיאה

הגדרת סשן בדיקה

השגיאות האלה נשלחות באופן סינכרוני על ידי enableTestSession().

קוד שגיאה סיבה הפעולה המומלצת
TEST_SESSION_ALREADY_ENABLED
(55508)
הפונקציה enableTestSession() הופעלה יותר מפעם אחת באותו תהליך של האפליקציה. FirebasePhoneNumberVerification.getInstance() מחזירה את אותו מופע בכל פעם, כך שזה קורה גם כשנוצרת מחדש Activity שקוראת לה. מפעילים את enableTestSession() פעם אחת בכל תהליך, למשל ב-Application.onCreate(). הפעלת הספרייה במצב בדיקה
INVALID_TEST_NUMBER_ID
(55507)
הטוקן לבדיקה שהועבר אל enableTestSession() ריק. מוודאים שה-build מעביר את הטוקן שנוצר במסוף Firebase, וקוראים ל-enableTestSession() רק כשהטוקן לא ריק.

אימות

השגיאות האלה גורמות לכך שה-Task שמוחזר על ידי getVerifiedPhoneNumber() נכשל.

קוד שגיאה סיבה הפעולה המומלצת
CREDENTIAL_MANAGER_ERROR
(55506)
‫Android Credential Manager לא החזיר את מספר הטלפון. אם הערך של cause של החריגה הוא GetCredentialCancellationException, סביר להניח שהמשתמש סגר את מסך ההסכמה. להציע דרך אחרת לאימות מספר הטלפון, כמו SMS. אל תנסו שוב באופן אוטומטי, כי המשתמש יראה שוב את מסך ההסכמה.
CARRIER_NOT_SUPPORTED
(55501)
הספק של כרטיס ה-SIM שנבחר לא נתמך, או שבמכשיר אין את פרטי המינוי שנדרשים לאימות. לעבור לשיטת אימות אחרת, כמו SMS.
UNSUPPORTED_OPERATION
(55505)
האפליקציה Firebase PNV לא זמינה לבקשה הזו במכשיר. לעבור לשיטת אימות אחרת, כמו SMS.
PREFLIGHT_CHECK_FAILED
(55504)
ה-backend של Firebase PNV לא הצליח ליצור את בקשת האימות לפני שמסך ההסכמה הוצג. לעבור לשיטת אימות אחרת, כמו SMS. אם זה קורה בכל בקשה, צריך לבדוק שהאפליקציה מוגדרת בצורה נכונה (ראו שדרוג למצב ייצור).
INTEGRITY_CHECK_FAILED
(55503)
המכשיר או האפליקציה נכשלו בבדיקת תקינות. לעבור לשיטת אימות אחרת, כמו SMS.
INVALID_DIGITAL_CREDENTIAL_RESPONSE
(55502)
לא ניתן היה לקרוא את התגובה מ-Credential Manager, או שלא ניתן היה להחליף אותה במספר טלפון מאומת. לעבור לשיטת אימות אחרת, כמו SMS.
INVALID_TEST_NUMBER_ID
(55507)
במצב בדיקה, הקצה העורפי של Firebase PNV דחה את הטוקן לבדיקה, למשל כי פג התוקף שלו. לאסימוני בדיקה יש TTL של 7 ימים. טוקן בדיקה שנדחה בדרך כלל מדווח על הקוד הזה. אם מופיעות שגיאות אחרות במצב בדיקה, צריך גם לבדוק שהטוקן עדכני. יוצרים אסימון בדיקה חדש במסוף Firebase ויוצרים מחדש את האפליקציה.
ACTIVITY_CONTEXT_REQUIRED
(55509)
הערך Context שהועבר אל getVerifiedPhoneNumber() הוא לא Activity. ה-method צריך Activity כדי להציג את מסך ההסכמה. מעבירים את ה-Activity הנוכחי. זהו באג באפליקציה, ולא מצב שצריך לטפל בו בזמן הריצה.

בדיקת תמיכה

ה-Task שמוחזר על ידי getVerificationSupportInfo() נכשל רק אם לא ניתן להריץ את הבדיקה עצמה. במקרה כזה, הערך של errorCode הוא ערך של CommonStatusCodes ב-Google Play Services או 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 אם ה-backend דוחה את טוקן הבדיקה.
  • הקריאה שלכם ל-Credential Manager מחזירה GetCredentialException, שאתם מטפלים בה ישירות.

מכשירים וכרטיסי SIM לא נתמכים

כשהערך של isSupported() הוא false בכרטיס SIM, הפונקציה getReason() מחזירה אחד מהערכים הבאים של VerificationSupportStatus:

ערך משמעות
INCAPABLE_DUE_TO_CARRIER_UNSUPPORTED הספק של כרטיס ה-SIM לא נתמך. לרשימת הספקים הנתמכים
INCAPABLE_DUE_TO_ANDROID_VERSION במכשיר פועלת גרסה של Android שקודמת ל-Android 10 (רמת API ‏29).
INCAPABLE_DUE_TO_SIM_STATE כרטיס ה-SIM לא מוכן. כרטיס SIM נעול או כזה שעדיין נטען יכול גם לדווח על INCAPABLE_DUE_TO_CARRIER_UNSUPPORTED, כי הספק נבדק קודם.

בכל אחד מהמקרים האלה, צריך להשתמש בשיטת אימות אחרת, כמו SMS, בשביל כרטיס ה-SIM הזה.

דוגמה

בדוגמה הבאה מטופלות השגיאות שאפליקציה טיפוסית צריכה להבחין ביניהן כשמפעילים את getVerifiedPhoneNumber():

Kotlin

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() הוא תהליך אימות מספר הטלפון הקיים באפליקציה.

השלבים הבאים