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

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

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

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

قبل البدء

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

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

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

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: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.

(بديل)  إضافة تبعيات مكتبة 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:17.0.0")
}

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

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

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

   ملاحظة: لإنشاء رمز مميّز اختباري، يجب أن يكون لديك دور مشرف إدارة الهوية وإمكانية الوصول (IAM) لتأكيد رقم الهاتف في Firebase. إذا لم تكن مسجِّلاً الدخول إلى وحدة تحكّم "Firebase" بصفتك مالك المشروع، قد تحتاج إلى الحصول على هذا الدور يدويًا. يمكن إجراء ذلك في صفحة إدارة الهوية وإمكانية الوصول ضمن وحدة تحكّم Google Cloud.

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 في الجهاز.

Kotlin

val fpnv = FirebasePhoneNumberVerification.getInstance()

val supportInfo: Task<List<VerificationSupportResult>> = fpnv.getVerificationSupportInfo()

// Cache this value for 1 hour to avoid exceeding per-device quota.
val dcp: Task<String> = fpnv.getDigitalCredentialPayload("")

Tasks.whenAllSuccess<Any>(supportInfo, dcp)
    .addOnSuccessListener { results ->
        // Triggered only if BOTH tasks succeed
        val supportInfo = results[0] as List<VerificationSupportResult>
        val dcp = results[1] as String
        if (supportInfo.any { it.isSupported() }) {
            // Both checks passed. Proceed to getVerifiedPhoneNumber
            // (see the next step).
        }
    }
    .addOnFailureListener { exception ->
        // Triggered if AT LEAST ONE task fails. Fallback to SMS
    }

مشكلة معروفة: إذا لم يجتَز الجهاز عمليات التحقّق من متطلبات حماية الجهاز، ستعرض واجهة برمجة التطبيقات getVerificationSupportInfo() رسالة نجاح، ولكن ستتعذّر عملية التحقّق من خلال getVerifiedPhoneNumber(). كحل بديل، يمكنك استدعاء getDigitalCredentialPayload() بالإضافة إلى getVerificationSupportInfo() والتحقّق من النتيجتين، كما هو موضّح أعلاه.

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

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

Kotlin

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() عملية تأكيد رقم الهاتف بالكامل، بما في ذلك:

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

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

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

عند تعذُّر إجراء طلب Firebase PNV، يكون الاستثناء هو FirebasePhoneNumberVerificationException. استخدِم errorCode لتحديد الإجراء التالي، مثلاً استخدام طريقة التحقّق عبر الرسائل القصيرة في حال رفض المستخدم منح موافقته. يمكنك الاطّلاع على معالجة أخطاء 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.