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

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

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

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

قبل البدء

  1. يجب أن تكون لديك حقوق مالك المشروع لإكمال خطوات الإعداد، بما في ذلك التحقّق من العلامة التجارية لـ OAuth.

  2. يجب أن تكون لديك سياسة خصوصية متاحة للجميع لإكمال عملية التحقّق من العلامة التجارية لـ OAuth. يمكنك استخدام Firebase Hosting لإنشاء تطبيق أساسي على الويب لـ استضافة سياسة الخصوصية التجريبية.

  3. تأكَّد من توفُّر شريحة SIM من أحد مشغّلي شبكات الجوّال المتوافقين لإجراء الاختبار.

1. إعداد مشروع Firebase

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

  2. إذا لم يسبق لك تحديد الملف المرجعي لشهادة SHA-256 الخاصة بتطبيقك في Firebase، يمكنك إجراء ذلك من إعدادات المشروع. راجِع صفحة المصادقة على العميل للحصول على تفاصيل حول كيفية الحصول على الملف المرجعي لشهادة SHA-256 الخاصة بتطبيقك.

  3. عليك إكمال عملية الإعداد لأول مرة في Firebase وحدة التحكّم. ويشمل ذلك التحقّق من العلامة التجارية لـ OAuth، ومراجعة سياسة الخصوصية. إذا كنت تُعدّ تطبيقًا تجريبيًا غير مخصّص للإنتاج ، يمكنك استخدام Firebase Hosting لإنشاء تطبيق أساسي على الويب لاستضافة سياسة الخصوصية التجريبية.

  4. Firebase PNV تتطلّب خطة Blaze. إذا لم يسبق لك ترقية مشروعك إلى خطة Blaze المَرِنة، سيُطلب منك إجراء ذلك أثناء الإعداد.

    على الرغم من أنّ Firebase PNV تتطلّب ربط حساب فوترة بمشروعك على Firebase ، لن يتم تحصيل رسوم منك مقابل الخدمة خلال مرحلة المعاينة.

  5. في صفحة بيانات الاعتماد في "وحدة التحكّم"، افتح مفتاح واجهة برمجة تطبيقات Android وأضِف واجهة برمجة التطبيقات Firebase Phone Number Verification إلى قائمة واجهات برمجة التطبيقات المحدّدة.

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

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

dependencies {
    // Add the dependency for the Firebase Phone Number Verification library
    implementation("com.google.firebase:firebase-pnv:16.0.0")
}

3. ننصحك بما يلي: التحقّق من توفُّر ميزة Firebase PNV

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

للتحقّق من توافق الجهاز، استدعِ الطريقة getVerificationSupportInfo():

Kotlin 

import com.google.firebase.pnv.FirebasePhoneNumberVerification

// Get an instance of the SDK.
val fpnv = FirebasePhoneNumberVerification.getInstance()

// Check all SIMs for support.
fpnv.getVerificationSupportInfo()
  .addOnSuccessListener { results ->
    if (results.any { it.isSupported() }) {
      // At least one SIM is supported; proceed with FPNV flow
    } else {
      // No SIMs are supported, so fall back to SMS verification.
    }
  }
  .addOnFailureListener { e ->
    // Handle error.
  }

تعرض الطريقة getVerificationSupportInfo() قائمة بكائنات VerificationSupportResult، واحد لكل فتحة شريحة SIM. إذا كانت إحدى شرائح SIM على الأقل متوافقة، يمكنك المتابعة باستخدام تدفق Firebase PNV.

4. بدء تدفق التحقّق

لبدء تدفق Firebase PNV، أنشِئ مثيلاً جديدًا من FirebasePhoneNumberVerification، مع تمرير سياق Activity. يكون سياق Activity ضروريًا لكي تعرض حزمة تطوير البرامج (SDK) شاشة طلب الموافقة للمستخدم. بعد ذلك، استدعِ الطريقة getVerifiedPhoneNumber() للكائن:

Kotlin 

import com.google.firebase.pnv.FirebasePhoneNumberVerification

// Get an instance of the SDK _with an Activity context_:
val fpnv = FirebasePhoneNumberVerification.getInstance(this@MainActivity)

// Call getVerifiedPhoneNumber
fpnv.getVerifiedPhoneNumber()
  .addOnSuccessListener { result ->
    val phoneNumber = result.getPhoneNumber()
    val token = result.getToken()
    // Verification successful. Send token to your backend.
  }
  .addOnFailureListener { e ->
    // Handle failures, such as the user declining consent or a network error.
  }

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

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

5. استخدام الرمز المميّز Firebase PNV

إذا نجح التدفق، تعرض الطريقة getVerifiedPhoneNumber() رقم الهاتف الذي تم التحقّق منه ورمزًا مميّزًا موقّعًا يتضمّنه. يمكنك استخدام هذه البيانات في تطبيقك كما هو موضّح في سياسة الخصوصية.

إذا كنت تستخدم رقم الهاتف الذي تم التحقّق منه خارج عميل التطبيق، عليك تمرير الرمز المميّز بدلاً من رقم الهاتف نفسه حتى تتمكّن من التحقّق من سلامته عند استخدامه. للتحقّق من الرمز المميّز، يمكنك استخدام أي مكتبة للتحقّق من رموز JWT المميّزة. استخدِم المكتبة للتحقّق من كل مما يلي:

  • تم ضبط عنوان typ على JWT.

  • تم توقيع الرمز المميّز باستخدام أحد المفاتيح المنشورة على نقطة نهاية JWKS Firebase PNV باستخدام خوارزمية ES256:

    https://fpnv.googleapis.com/v1beta/jwks

  • يتضمّن عنصر التحكّم "الجهة المُصدرة" رقم مشروعك على Firebase ويكون بالتنسيق التالي:

    https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER

    يمكنك العثور على رقم مشروع Firebase الخاص بك في صفحة إعدادات المشروع في "وحدة تحكّم Firebase".

  • عنصر التحكّم "الجمهور" هو قائمة تتضمّن رقم مشروعك على Firebase ورقم تعريف المشروع ويكون بالتنسيق التالي:

    [
  https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_NUMBER,
  https://fpnv.googleapis.com/projects/FIREBASE_PROJECT_ID,
]

  • لم تنتهِ صلاحية الرمز المميّز.

مثال

كمثال موجز، يتلقّى تطبيق Express.js التالي رمزًا مميّزًا Firebase PNV من طلب HTTP POST ويستخدم مكتبة للتحقّق من رموز JWT المميّزة للتحقّق من توقيع الرمز المميّز وعناصر التحكّم فيه:

Node.js

import express from "express";
import { JwtVerifier } from "aws-jwt-verify";

// Find your Firebase project number in the Firebase console.
const FIREBASE_PROJECT_NUMBER = "123456789";

// The issuer and audience claims of the FPNV token are specific to your
// project.
const issuer = `https://fpnv.googleapis.com/projects/${FIREBASE_PROJECT_NUMBER}`;
const audience = `https://fpnv.googleapis.com/projects/${FIREBASE_PROJECT_NUMBER}`;

// The JWKS URL contains the current public signing keys for FPNV tokens.
const jwksUri = "https://fpnv.googleapis.com/v1beta/jwks";

// Configure a JWT verifier to check the following:
// - The token is signed by Google
// - The issuer and audience claims match your project
// - The token has not yet expired (default behavior)
const fpnvVerifier = JwtVerifier.create({ issuer, audience, jwksUri });

const app = express();

app.post('/verifiedPhoneNumber', async (req, res) => {
    if (!req.body) return res.sendStatus(400);
    // Get the token from the body of the request.
    const fpnvToken = req.body;
    try {
        // Attempt to verify the token using the verifier configured
        previously.
        const verifiedPayload = await fpnvVerifier.verify(fpnvToken);

        // If verification succeeds, the subject claim of the token contains the
        // verified phone number. You can use this value however it's needed by
        // your app.
        const verifiedPhoneNumber = verifiedPayload.sub;
        // (Do something with it...)

        return res.sendStatus(200);
    } catch {
        // If verification fails, reject the token.
        return res.sendStatus(400);
    }
});

app.listen(3000);

تسجيل الدخول إلى تطبيق Firebase

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