توضّح صفحة بدء استخدام Firebase Phone Number Verification تفاصيل كيفية الدمج مع Firebase PNV باستخدام طريقة getVerifiedPhoneNumber() التي تعالج عملية Firebase PNV بالكامل، بدءًا من الحصول على موافقة المستخدم وحتى إجراء طلبات الشبكة اللازمة إلى الخلفية في Firebase PNV.
يُنصح معظم المطوّرين باستخدام واجهة برمجة التطبيقات ذات الطريقة الواحدة (getVerifiedPhoneNumber()). ومع ذلك، إذا كنت بحاجة إلى التحكّم بشكل أكثر دقة في التفاعل مع
Android Credential Manager، على سبيل المثال، لطلب بيانات اعتماد أخرى مع
رقم الهاتف، توفّر مكتبة
Firebase PNV أيضًا الطريقتَين التاليتَين، حيث تتعامل كل منهما مع
تفاعل مختلف مع الخلفية Firebase PNV:
- يحصل تطبيق "
getDigitalCredentialPayload()" على طلب موقَّع من الخادم، والذي ستستخدمه لاستدعاء Credential Manager. - يستبدل
exchangeCredentialResponseForPhoneNumber()الردّ من Credential Manager برمز مميّز موقَّع يحتوي على رقم الهاتف الذي تم تأكيده. وستتم الفوترة في هذه الخطوة.
بين استدعاء كل من هذه الطرق، تقع على عاتقك مسؤولية التعامل مع التفاعل مع واجهات برمجة تطبيقات Credential Manager في Android. تقدّم هذه الصفحة نظرة عامة على كيفية تنفيذ هذا المسار المكوّن من ثلاثة أجزاء.
قبل البدء
يمكنك إعداد مشروع Firebase واستيراد تبعيات Firebase PNV كما هو موضّح في صفحة البدء.
1. الحصول على حمولة طلب "بيانات الاعتماد الرقمية"
استخدِم طريقة getDigitalCredentialPayload() لإنشاء طلب للحصول على رقم هاتف الجهاز. في الخطوة التالية، سيكون هذا الطلب هو الحمولة
لتفاعلك مع Credential Manager API.
Kotlin
// This instance does not require an Activity context.
val fpnv = FirebasePhoneNumberVerification.getInstance()
// Your request should include a nonce, which will propagate through the flow
// and be present in the final response from FPNV. See the section "Verifying
// the Firebase PNV token" for details on generating and verifying this.
val nonce = fetchNonceFromYourServer()
fpnv.getDigitalCredentialPayload(nonce, "https://example.com/privacy-policy")
.addOnSuccessListener { fpnvDigitalCredentialPayload ->
// Use the payload in the next step.
// ...
}
.addOnFailureListener { e -> /* Handle payload fetch failure */ }
2. تقديم طلب للحصول على بيانات اعتماد رقمية باستخدام Credential Manager
بعد ذلك، مرِّر الطلب إلى Credential Manager.
لإجراء ذلك، عليك تضمين حمولة الطلب في طلب
DigitalCredential API. يجب أن يتضمّن هذا الطلب الرمز نفسه الذي أرسلته إلى
getDigitalCredentialPayload().
Kotlin
// This example uses string interpolation for clarity, but you should use some kind of type-safe
// serialization method.
fun buildDigitalCredentialRequestJson(nonce: String, fpnvDigitalCredentialPayload: String) = """
{
"requests": [
{
"protocol": "openid4vp-v1-unsigned",
"data": {
"response_type": "vp_token",
"response_mode": "dc_api",
"nonce": "$nonce",
"dcql_query": { "credentials": [$fpnvDigitalCredentialPayload] }
}
}
]
}
""".trimIndent()
بعد ذلك، يمكنك إرسال الطلب باستخدام واجهة Credential Manager API:
Kotlin
suspend fun makeFpnvRequest(
context: Activity, nonce: String, fpnvDigitalCredentialPayload: String): GetCredentialResponse {
// Helper function to build the digital credential request (defined above).
// Pass the same nonce you passed to getDigitalCredentialPayload().
val digitalCredentialRequestJson =
buildDigitalCredentialRequestJson(nonce, fpnvDigitalCredentialPayload)
// CredentialManager requires an Activity context.
val credentialManager = CredentialManager.create(context)
// Build a Credential Manager request that includes the Firebase PNV option. Note that
// you can't combine the digital credential option with other options.
val request = GetCredentialRequest.Builder()
.addCredentialOption(GetDigitalCredentialOption(digitalCredentialRequestJson))
.build()
// getCredential is a suspend function, so it must run in a coroutine scope,
val cmResponse: GetCredentialResponse = try {
credentialManager.getCredential(context, request)
} catch (e: GetCredentialException) {
// If the user cancels the operation, the feature isn't available, or the
// SIM doesn't support the feature, a GetCredentialCancellationException
// will be returned. Otherwise, a GetCredentialUnsupportedException will
// be returned with details in the exception message.
throw e
}
return cmResponse
}
إذا نجح طلب البيانات من Credential Manager، ستحتوي الاستجابة على مستند تعريف رقمي يمكنك استخراجه باستخدام رمز برمجي مثل المثال التالي:
Kotlin
val dcApiResponse = extractApiResponse(cmResponse)
fun extractApiResponse(response: GetCredentialResponse): String {
val credential = response.credential
when (credential) {
is DigitalCredential -> {
val json = JSONObject(credential.credentialJson)
val firebaseJwtArray =
json.getJSONObject("data").getJSONObject("vp_token").getJSONArray("firebase")
return firebaseJwtArray.getString(0)
}
else -> {
// Handle any unrecognized credential type here.
Log.e(TAG, "Unexpected type of credential ${credential.type}")
}
}
}
3- استبدال استجابة بيانات الاعتماد الرقمية برمز Firebase PNV المميّز
أخيرًا، يمكنك استدعاء طريقة exchangeCredentialResponseForPhoneNumber() لتبادل استجابة بيانات الاعتماد الرقمية برقم الهاتف الذي تم التحقّق منه ورمز Firebase PNV المميّز:
Kotlin
fpnv.exchangeCredentialResponseForPhoneNumber(dcApiResponse)
.addOnSuccessListener { result ->
val phoneNumber = result.getPhoneNumber()
// Verification successful
}
.addOnFailureListener { e -> /* Handle exchange failure */ }
ستؤدي هذه الخطوة إلى بدء الفوترة عند اكتمالها بنجاح وإرجاع رقم الهاتف الذي تم التحقّق منه إلى تطبيقك.
4. جارٍ التحقّق من الرمز المميّز "Firebase PNV"
إذا نجحت العملية، ستعرض طريقة getVerifiedPhoneNumber() رقم الهاتف الذي تم التحقّق منه ورمزًا مميزًا موقَّعًا يحتوي عليه. يمكنك استخدام هذه البيانات في تطبيقك
كما هو موثّق في سياسة الخصوصية.
إذا كنت تستخدم رقم الهاتف الذي تم التحقّق منه خارج برنامج التطبيق، عليك تمرير الرمز المميّز بدلاً من رقم الهاتف نفسه حتى تتمكّن من التحقّق من سلامته عند استخدامه. للتحقّق من الرموز المميّزة، عليك تنفيذ نقطتَي نهاية:
- نقطة نهاية لإنشاء رقم خاص يُستخدم لمرة واحدة
- نقطة نهاية للتحقّق من الرموز المميّزة
يعود إليك تنفيذ نقاط النهاية هذه، وتوضّح الأمثلة التالية كيفية تنفيذها باستخدام Node.js وExpress.
إنشاء أرقام عشوائية تُستخدم لمرة واحدة
هذه نقطة النهاية مسؤولة عن إنشاء وتخزين قيم الاستخدام الواحد مؤقتًا والتي تسمى رموز التحقق، والتي تُستخدم لمنع هجمات إعادة التشغيل ضد نقاط النهاية الخاصة بك. على سبيل المثال، قد يكون لديك مسار Express محدّد على النحو التالي:
Node.js
app.get('/fpnvNonce', async (req, res) => {
const nonce = crypto.randomUUID();
// TODO: Save the nonce to a database, key store, etc.
// You should also assign the nonce an expiration time and periodically
// clear expired nonces from your database.
await persistNonce({
nonce,
expiresAt: Date.now() + 180000, // Give it a short duration.
});
// Return the nonce to the caller.
res.send({ nonce });
});
هذه هي نقطة النهاية التي ستستدعيها دالة العنصر النائب fetchNonceFromYourServer() في الخطوة 1. سيتم نشر الرقم الخاص من خلال طلبات الشبكة المختلفة التي ينفّذها العميل، وسيعود في النهاية إلى الخادم في الرمز المميّز Firebase PNV. في الخطوة التالية، عليك التحقّق من أنّ الرمز المميّز يحتوي على رقم خاص تم إنشاؤه.
التحقّق من الرموز المميّزة
تتلقّى نقطة النهاية هذه رموز Firebase PNV المميّزة من العميل وتتحقّق من صحتها. للتحقّق من صحة رمز مميّز، عليك مراجعة ما يلي:
تم ضبط عنوان
typعلىJWT.يتم توقيع الرمز المميّز باستخدام أحد المفاتيح المنشورة في نقطة نهاية Firebase PNV JWKS باستخدام خوارزمية
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 على النحو التالي:
Node.js
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 begavior)
const fpnvVerifier = JwtVerifier.create({ issuer, audience, jwksUri });
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);
// Now that you've verified the signature and claims, verify the nonce.
// TODO: Try to look up the nonce in your database and remove it if it's
// found; if it's not found or it's expired, throw an error.
await testAndRemoveNonce(verifiedPayload.nonce);
// Only after verifying the JWT signature, claims, and nonce, get the
// verified phone number from the subject claim.
// 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);
}
});