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

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

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

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

قبل البدء

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

1. إعداد مشروعك على Firebase

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

2. تتطلّب "Firebase PNV" خطة Blaze. إذا لم تكن قد رقّيت مشروعك إلى خطة أسعار Blaze بنظام الدفع حسب الاستخدام، يُرجى إجراء ذلك.

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

4. افتح مشروعك على Firebase في "منصة Google Cloud" وفعِّل واجهة برمجة التطبيقات Firebase Phone Number Verification API.

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-beta01")
}

3- اختياري: التحقّق من توفّر دعم Firebase PNV

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

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

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() الخاصة بالعنصر:

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

// Call getVerifiedPhoneNumber
fpnv.getVerifiedPhoneNumber("https://example.com/privacy-policy")
  .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. استخدِم المكتبة للتأكّد من كل ما يلي:

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

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

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

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

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

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

مثال

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

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