كيفية معالجة أخطاء ميزة "تأكيد رقم الهاتف" في 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"، يمكن أن تكون قيمة errorCode أيضًا CommonStatusCodes، مثل NETWORK_ERROR.

لا يُعدّ الجهاز أو شريحة SIM غير المتوافقَين خطأً. getVerificationSupportInfo() بنجاح، ويتم الإبلاغ عن isSupported() على أنّه false لشريحة SIM هذه، ويخبرك getReason() بالسبب. يُرجى الاطّلاع على الأجهزة وشرائح SIM غير المتوافقة.

رموز الخطأ

إعداد جلسة الاختبار

يتم عرض هذه الأخطاء بشكل متزامن من خلال enableTestSession().

التحقق

تؤدي هذه الأخطاء إلى تعذُّر تنفيذ Task الذي تم إرجاعه من قِبل getVerifiedPhoneNumber().

التحقّق من الدعم

لا يتعذّر تنفيذ Task الذي تعرضه getVerificationSupportInfo() إلا إذا تعذّر إجراء عملية التحقّق نفسها. في هذه الحالة، تكون قيمة errorCode إما قيمة CommonStatusCodes في "خدمات Google Play" أو 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 إذا رفضت الخلفية الرمز المميّز التجريبي.
• يؤدي طلبك إلى Credential Manager إلى ظهور الخطأ GetCredentialException، والذي يمكنك معالجته مباشرةً.

الأجهزة وشرائح SIM غير المتوافقة

عندما تكون قيمة isSupported() هي false لشريحة SIM، تعرض السمة getReason() إحدى قيم VerificationSupportStatus التالية:

في كلتا الحالتَين، استخدِم طريقة التحقق (من البطاقة) أخرى، مثل رسالة SMS، لشريحة SIM هذه.

مثال

يتعامل المثال التالي مع الأخطاء التي يحتاج تطبيق عادي إلى تمييزها عند طلب 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.
• للتحقّق من الرمز المميّز على خادمك، يُرجى الاطّلاع على مقالة التحقّق من رموز Firebase PNV المميّزة.