بدء استخدام ميزة "تأكيد رقم الهاتف" في Firebase على Android

توضّح هذه الصفحة كيفية بدء استخدام Firebase Phone Number Verification في تطبيق Android. يمكنك الاطّلاع على النظرة العامة للحصول على وصف عام لهذه الميزة.

باتّباع الخطوات الواردة في هذه الصفحة، يمكنك البدء بسرعة في تنفيذ مسارات المستخدمين في Firebase PNV. لأغراض الاختبار، عليك إنشاء رمز مميّز مخصّص للاختبار فقط يتم تحويله إلى رقم هاتف مزيّف. باستخدام هذا الرمز المميّز التجريبي، يمكنك البدء في إضافة Firebase PNV إلى تطبيقك بدون الحاجة إلى حساب فوترة أو جهاز مزوّد بشريحة SIM حقيقية.

بعد أن تشعر بالرضا عن تجربة مستخدم Firebase PNV في تطبيقك، يمكنك اتّباع بعض الخطوات الإضافية لإنتاج تطبيقك.

قبل البدء

• أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك.

• يُرجى التأكّد من أنّ تطبيقك يستوفي المتطلبات التالية:

  • أن يكون الإصدار minSdk من تطبيقك هو 24 (Android 7.0) أو إصدار أحدث
  • يجب أن يتوفّر في الجهاز أو المحاكي "خدمات Google Play". بالنسبة إلى المحاكيات، استخدِم صورة نظام تتضمّن Google Play.
  • للتحقّق من أرقام الهواتف الحقيقية في الإصدار العلني، يجب أن يعمل الجهاز بنظام التشغيل Android 9 (مستوى واجهة برمجة التطبيقات 28) أو إصدار أحدث وأن يستخدم شريحة SIM من مشغّل شبكة جوّال متوافق. لا يتطلّب وضع الاختبار، الموضّح في هذه الصفحة، شريحة SIM حقيقية.

1. إضافة مكتبة Firebase PNV إلى تطبيقك

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:35.1.0"))

    // Add the dependencies for the Firebase Phone Number Verification libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-pnv")
}

باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام التشغيل Android.

dependencies {
    // Add the dependencies for the Firebase Phone Number Verification libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-pnv:17.0.0")
}

2. بدء مكتبة Firebase PNV في وضع الاختبار

1. في وحدة تحكّم Firebase، انتقِل إلى علامة التبويب الأمان > تأكيد الحساب عبر الهاتف > الإعدادات > الاختبار.

2. انقر على إنشاء رمز مميّز، واختَر رمز بلد، ثم انقر على إنشاء رمز مميّز مرة أخرى لإنشاء الرمز المميّز ونسخه.

3. اجعل الرمز المميّز متاحًا لإصدارات تطبيقك المخصّصة لتصحيح الأخطاء بدون ترميزه بشكل ثابت في الرمز المصدري. يجب التعامل مع الرمز المميّز كبيانات اعتماد وإبقاؤه خارج نظام التحكّم في الإصدارات. على سبيل المثال، أضِفه إلى ملف local.properties الخاص بمشروعك، والذي لا يتم التحقّق منه في نظام التحكّم في الإصدارات:

   fpnv.testToken=COPIED_TOKEN_STRING
   

   بعد ذلك، اعرضه كحقل BuildConfig في ملف build.gradle.kts للوحدة (على مستوى التطبيق). يقرأ المثال التالي أيضًا متغيّر بيئة FPNV_TEST_TOKEN، وهو مفيد على خوادم CI التي لا تحتوي على ملف local.properties. تحصل إصدارات الإصدار على قيمة فارغة:

   // At the top of the file:
   import java.util.Properties
   
   val localProperties = Properties().apply {
       rootProject.file("local.properties").takeIf { it.exists() }
           ?.inputStream()?.use { load(it) }
   }
   val fpnvTestToken = System.getenv("FPNV_TEST_TOKEN")?.takeIf { it.isNotEmpty() }
       ?: localProperties.getProperty("fpnv.testToken", "")
   
   android {
       buildFeatures {
           buildConfig = true
       }
       buildTypes {
           debug {
               buildConfigField("String", "FPNV_TEST_TOKEN", "\"$fpnvTestToken\"")
           }
           release {
               buildConfigField("String", "FPNV_TEST_TOKEN", "\"\"")
           }
       }
   }
   

4. في تطبيقك، فعِّل جلسة اختبار مرة واحدة لكل عملية تطبيق:

   Kotlin

   تعرض دالة FirebasePhoneNumberVerification.getInstance() المثيل نفسه لـ FirebaseApp التلقائي في كل مرة يتم استدعاؤها، لذا يمكنك استخدامها لجميع استدعاءات Firebase PNV.

   يجب استدعاء enableTestSession() مرة واحدة فقط لكل عملية تطبيق. يؤدي إجراء مكالمة ثانية إلى ظهور FirebasePhoneNumberVerificationException مع رمز الخطأ TEST_SESSION_ALREADY_ENABLED، لذا لا تُجرِ المكالمة من Activity، والذي يمكن إعادة إنشائه (على سبيل المثال، عند تدوير الشاشة). بدلاً من ذلك، يمكنك استدعاؤها من فئة Application:

   import android.app.Application
   import android.util.Log
   import com.google.firebase.pnv.FirebasePhoneNumberVerification
   
   class MyApplication : Application() {
       override fun onCreate() {
           super.onCreate()
           if (!BuildConfig.DEBUG) return
           if (BuildConfig.FPNV_TEST_TOKEN.isEmpty()) {
               Log.w("MyApplication", "No Firebase PNV test token; test mode is off.")
               return
           }
           FirebasePhoneNumberVerification.getInstance()
               .enableTestSession(BuildConfig.FPNV_TEST_TOKEN)
       }
   }
   

   سجِّل الفئة في بيان تطبيقك:

   <application
       android:name=".MyApplication"
       ... >
   

تبلغ مدة صلاحية الرموز المميّزة الاختبارية 7 أيام، وبعد هذه الفترة، يجب إنشاء رمز مميّز جديد لتفعيل جلسات الاختبار. لا يؤدي الرمز المميّز المنتهية صلاحيته إلى حدوث خطأ إلا عند طلب getVerifiedPhoneNumber(). تعمل الرموز المميّزة الاختبارية على الأجهزة الفعلية والمحاكيات التي تتضمّن "خدمات Google Play"، ما يجعلها مثالية لإنشاء نماذج أولية لتجربة المستخدم في تطبيقك. يمكنك أيضًا استخدامها للاختبار في CI/CD إذا استبدلت الرمز المميّز كل 7 أيام على الأقل.

يتم توقيع رموز أرقام الهاتف المميّزة التي يحصل عليها تطبيقك في وضع الاختبار مثل رموز الإنتاج المميّزة، ولكنّها تتضمّن المطالبة "test_number": true. يجب التأكّد من أنّ الخلفية في مرحلة الإنتاج ترفض الرموز المميّزة التي تتضمّن هذا الادعاء.

3- الإجراء المقترح: التحقّق من توفّر دعم Firebase PNV

لمساعدتك في تحديد وقت عرض واجهة المستخدم الخاصة بإدخال الرقم أو واجهة المستخدم التوضيحية، ننصحك بالتحقّق عند تشغيل التطبيق مما إذا كان الجهاز وشريحة SIM متوافقَين مع Firebase PNV. هذا فحص مسبق لا يتطلّب موافقة المستخدم. يمكنك استخدام نتيجة هذا الاختبار لتحديد ما إذا كنت تريد بدء عملية Firebase PNV أو استخدام طريقة بديلة لتأكيد رقم الهاتف، مثل الرسائل القصيرة SMS.

للتحقّق من توافق الجهاز، يمكنك استدعاء طريقة getVerificationSupportInfo(). عندما تكون جلسة الاختبار نشطة، تعرض هذه الطريقة دائمًا قائمة تحتوي على إدخال واحد متوافق لرمز الاختبار، بدون الاتصال بواجهة Firebase PNV الخلفية. هذا يعني أنّه لا يمكنك استخدام الإجراء الاحتياطي للأجهزة غير المتوافقة في وضع الاختبار. لاحقًا، بعد طرح تطبيقك في مرحلة الإنتاج، ستعرض هذه الطريقة نتيجة لكل شريحة SIM في الجهاز.

val fpnv = FirebasePhoneNumberVerification.getInstance()

// Check all SIMs for support.
fpnv.getVerificationSupportInfo()
    .addOnSuccessListener { results ->
        if (results.any { it.isSupported() }) {
            // At least one SIM is supported; okay to call getVerifiedPhoneNumber
            // (see the next step).
        } else {
            // No SIMs are supported, so fall back to SMS verification.
        }
    }
    .addOnFailureListener { e ->
        // Handle error.
    }

4. بدء عملية التحقّق

لبدء عملية Firebase PNV، يمكنك استدعاء طريقة getVerifiedPhoneNumber(). يجب تمرير Activity لأنّ الطريقة تعرض شاشة طلب الموافقة. إذا لم يكن Context من نوع Activity، مثل سياق Application، يتعذّر تنفيذ الطلب ويظهر رمز الخطأ ACTIVITY_CONTEXT_REQUIRED.

fpnv.getVerifiedPhoneNumber(this@MainActivity)
    .addOnSuccessListener { result ->
        // In test mode, this phone number will have a valid country code,
        // followed by all zeros.
        val phoneNumber = result.getPhoneNumber() // For display only.
        val token = result.getToken()

        // Verification successful. Send token to your backend, which reads
        // the verified phone number from it. (See Next steps.)
    }
    .addOnFailureListener { e ->
        // Handle failures, such as the user declining consent or a network
        // error.
    }

تنفّذ الطريقة getVerifiedPhoneNumber() عملية تأكيد رقم الهاتف بالكامل، بما في ذلك:

• استخدام واجهة Credential Manager في Android للحصول على موافقة المستخدم على مشاركة رقم هاتفه
• جارٍ إرسال الطلب إلى الخلفية في Firebase PNV.
• يتم عرض رمز مميّز يحتوي على رقم الهاتف الذي تم تأكيده للجهاز (في تطبيق إنتاج، يحدث ذلك عند إجراء الفوترة).

5- معالجة الأخطاء

عند تعذُّر إجراء مكالمة Firebase PNV، يكون الاستثناء هو FirebasePhoneNumberVerificationException. استخدِم errorCode لتحديد الإجراء التالي، مثلاً استخدام التحقّق من خلال رسالة قصيرة SMS في حال رفض المستخدم منح موافقته. يمكنك الاطّلاع على معالجة أخطاء Firebase PNV على Android لكل رمز خطأ، ووقت حدوثه، والإجراء المقترَح.

الخطوات التالية

• توضّح هذه الصفحة بالتفصيل كيفية التكامل مع "Firebase PNV" باستخدام واجهة برمجة التطبيقات الموحّدة التي تتطلّب طلبًا واحدًا. يؤدي استدعاء طريقة واحدة إلى معالجة مسار المستخدم في Firebase PNV بالكامل، بدءًا من الحصول على موافقة المستخدم وحتى إجراء طلبات الشبكة اللازمة إلى الخلفية في Firebase PNV. باستخدام هذه الطريقة، يمكنك تقليل خطوات الدمج إلى طلب إجراء واحد.

  ننصح معظم المطوّرين باستخدام واجهة برمجة التطبيقات هذه، ولكن إذا كانت لديك متطلبات محدّدة لا تلبّيها المكتبة، يمكنك الاطّلاع على صفحة تخصيص مسار Firebase Phone Number Verification للحصول على معلومات حول تنفيذ مسار مخصّص.

• إذا كنت تستخدم رقم الهاتف الذي تم التحقّق منه خارج برنامج العميل للتطبيق، يجب تمرير الرمز المميّز بدلاً من رقم الهاتف نفسه حتى تتمكّن من التحقّق من سلامته عند استخدامه. يُرجى الاطّلاع على التحقّق من رموز Firebase PNV المميّزة.

• لتسجيل دخول المستخدمين إلى "Firebase Authentication" باستخدام رقم هاتفهم الذي تم تأكيده، يُرجى الاطّلاع على مقالة المصادقة باستخدام Firebase من خلال "Firebase Phone Number Verification".

• للحصول على دليل تفصيلي لإنشاء نموذج تطبيق كامل، يمكنك تجربة الدرس التطبيقي حول الترميز في Firebase Phone Number Verification.

• بعد تنفيذ واختبار مسار Firebase PNV في تطبيقك ودمجه مع الخلفية، يمكنك طرح تطبيقك في مرحلة الإنتاج لبدء الحصول على أرقام هواتف حقيقية تم التحقّق منها. يُرجى الاطّلاع على الترقية إلى وضع الإنتاج.

• للاطّلاع على واجهة برمجة التطبيقات الكاملة، يُرجى مراجعة مرجع واجهة برمجة التطبيقات Firebase PNV.