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

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

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

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

قبل البدء

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

في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً ما يكون <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة Firebase Phone Number Verification لنظام التشغيل Android. ننصحك باستخدام الـ Firebase Android BoM للتحكّم في تحديد إصدار المكتبة. 

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.12.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.

(بديل)  إضافة تبعيات مكتبة Firebase بدون استخدام BoM

إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر الاعتمادية الخاص بها.

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

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:16.0.0")
}

2. تهيئة مكتبة Firebase PNV في "وضع الاختبار"

  1. في علامة التبويب الاختبار ضمن قسم Firebase "التحقّق من رقم الهاتف" في Firebase Console، انقر على الزر إنشاء رمز مميّز.

  2. في تطبيقك، عليك تهيئة عميل Firebase PNV لاستخدام جلسة اختبار:

    Kotlin

    استورِد المكتبة:

    import com.google.firebase.pnv.FirebasePhoneNumberVerification

    أنشِئ مثيلاً جديدًا لفئة FirebasePhoneNumberVerification و استخدِم هذا المثال لجميع طلبات Firebase PNV. لا تعرض الطريقة getInstance() عنصر سينغلتون، لذا عليك الاحتفاظ به بعد إنشائه.

    val fpnv = FirebasePhoneNumberVerification.getInstance(this@MainActivity)

    فعِّل جلسة اختبار باستخدام الرمز المميّز الذي أنشأته في الخطوة السابقة:

    fpnv.enableTestSession("COPIED_TOKEN_STRING")

    عليك استدعاء هذا الإجراء مرة واحدة فقط على مثال من FirebasePhoneNumberVerification، وسيؤدي استدعاؤه لاحقًا إلى ظهور خطأ.

تكون مدة بقاء الرموز المميّزة للاختبار 7 أيام، وبعد هذه الفترة، ستحتاج إلى إنشاء رمز مميّز جديد لتفعيل جلسات الاختبار. تعمل الرموز المميّزة للاختبار على الأجهزة الفعلية والمحاكيات، ما يجعلها مثالية لإنشاء نموذج أولي لتجربة المستخدم في تطبيقك أو للاختبار في عملية التكامل المستمر/النشر المستمر.

3. ننصحك بما يلي: التحقّق من إمكانية استخدام ميزة Firebase PNV

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

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

Kotlin 

// 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():

Kotlin 

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

    // Verification successful. Send token to your backend. (See Next Steps.)
  }
  .addOnFailureListener { e ->
    // Handle failures, such as the user declining consent or a network error.
  }

ينفّذ الإجراء getVerifiedPhoneNumber() مسار التحقّق من رقم الهاتف بالكامل، بما في ذلك:

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

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

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

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

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

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