مصادقة الهاتف

تتيح مصادقة الهاتف للمستخدمين تسجيل الدخول إلى Firebase باستخدام هواتفهم كأداة المصادقة. يتم إرسال رسالة قصيرة SMS إلى المستخدم (باستخدام رقم الهاتف المقدّم) تحتوي على رمز فريد. بعد تفويض الرمز، سيتمكّن المستخدم من تسجيل الدخول إلى Firebase.

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

لا تتوفر مصادقة الهاتف عبر Firebase في بعض البلدان. لمزيد من المعلومات، يُرجى الاطّلاع على الأسئلة الشائعة.

الإعداد

قبل بدء مصادقة الهاتف، تأكد من اتباع الخطوات التالية:

  1. فعِّل "الهاتف" كطريقة تسجيل الدخول في وحدة تحكُّم Firebase.
  2. Android: إذا لم يسبق لك ضبط تجزئة SHA-1 لتطبيقك في وحدة تحكُّم Firebase، يُرجى إجراء ذلك. يمكنك مراجعة مصادقة البرنامج للحصول على معلومات حول العثور على تجزئة SHA-1 لتطبيقك.
  3. iOS: في Xcode، يمكنك تفعيل الإشعارات الفورية لمشروعك والتأكُّد من ضبط مفتاح مصادقة أسماء نقاط الوصول (APNs) مع المراسلة عبر السحابة الإلكترونية من Firebase. بالإضافة إلى ذلك، يجب تفعيل أوضاع الخلفية للإشعارات عن بُعد. للاطّلاع على شرح تفصيلي لهذه الخطوة، يمكنك الاطّلاع على مستندات مصادقة الهاتف بنظام التشغيل iOS من Firebase.
  4. الويب: تأكَّد من إضافة نطاق تطبيقاتك إلى وحدة تحكُّم Firebase ضمن نطاقات إعادة توجيه OAuth.

ملاحظة؛ لا يمكن تسجيل الدخول باستخدام رقم الهاتف إلا على الأجهزة الحقيقية والويب. لاختبار مسار المصادقة على محاكيات الأجهزة، يُرجى الاطّلاع على الاختبار.

الاستخدام

توفِّر حزمة تطوير البرامج (SDK) لمصادقة Firebase الخاصة بتطبيق Flutter طريقتَين فرديتَين لتسجيل دخول المستخدم باستخدام رقم هاتفه. توفر الأنظمة الأساسية الأصلية (مثل Android وiOS) وظائف مختلفة للتحقق من رقم الهاتف عن الويب، لذلك توجد طريقتان لكل نظام أساسي بشكل حصري:

  • النظام الأساسي الأصلي: verifyPhoneNumber.
  • نظام الويب الأساسي: signInWithPhoneNumber.

محلي: verifyPhoneNumber

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

أولاً، عليك أن تطلب من المستخدم تقديم رقم هاتفه. بعد توفيرها، يمكنك استدعاء طريقة verifyPhoneNumber():

await FirebaseAuth.instance.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  verificationCompleted: (PhoneAuthCredential credential) {},
  verificationFailed: (FirebaseAuthException e) {},
  codeSent: (String verificationId, int? resendToken) {},
  codeAutoRetrievalTimeout: (String verificationId) {},
);

هناك 4 عمليات استدعاء منفصلة يجب التعامل معها، وستحدِّد كلّ منها كيفية تحديث واجهة مستخدم التطبيق:

  1. verificationcomplete: المعالجة التلقائية لرمز الرسائل القصيرة SMS على أجهزة Android
  2. verificationتعذّر: التعامل مع أحداث التعذُّر، مثل أرقام الهواتف غير الصالحة أو ما إذا تم تجاوز حصة رسائل SMS
  3. codeSent: التعامل مع حالات إرسال رمز إلى الجهاز من Firebase، يتم استخدامه لطلب المستخدمين بإدخال الرمز
  4. codeAutoRetrieval المضمّنة: يمكنك التعامل مع المهلة المحدّدة عند تعذُّر المعالجة التلقائية لرمز الرسائل القصيرة.

اكتمل إثبات الملكية

لن يتم طلب هذا المعالج إلا على أجهزة Android التي تتيح الحل التلقائي لرمز SMS.

عند تسليم رمز الرسائل القصيرة SMS إلى الجهاز، سيتحقق Android تلقائيًا من رمز الرسالة القصيرة SMS بدون مطالبة المستخدم بإدخال الرمز يدويًا. وفي حال وقوع هذا الحدث، يتم توفير PhoneAuthCredential تلقائيًا يمكن استخدامه لتسجيل الدخول باستخدام رقم هاتف المستخدم أو ربطه.

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  verificationCompleted: (PhoneAuthCredential credential) async {
    // ANDROID ONLY!

    // Sign the user in (or link) with the auto-generated credential
    await auth.signInWithCredential(credential);
  },
);

تعذّر التحقق

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

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  verificationFailed: (FirebaseAuthException e) {
    if (e.code == 'invalid-phone-number') {
      print('The provided phone number is not valid.');
    }

    // Handle other errors
  },
);

تم إرسال الرمز

عندما يرسل Firebase رمز رسالة قصيرة SMS إلى الجهاز، يتم تشغيل هذا المعالج باستخدام verificationId وresendToken (لا يتوفّر رمز resendToken إلا على أجهزة Android، وستعرض أجهزة iOS القيمة null دائمًا).

بعد ظهور الرسالة، سيكون الوقت مناسبًا لتحديث واجهة مستخدم التطبيق لمطالبة المستخدم بإدخال رمز الرسائل القصيرة SMS الذي يتوقعه. بعد إدخال رمز الرسالة القصيرة SMS، يمكنك الجمع بين رقم تعريف إثبات الملكية ورمز الرسالة القصيرة SMS لإنشاء PhoneAuthCredential جديد:

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  codeSent: (String verificationId, int? resendToken) async {
    // Update the UI - wait for the user to enter the SMS code
    String smsCode = 'xxxx';

    // Create a PhoneAuthCredential with the code
    PhoneAuthCredential credential = PhoneAuthProvider.credential(verificationId: verificationId, smsCode: smsCode);

    // Sign the user in (or link) with the credential
    await auth.signInWithCredential(credential);
  },
);

وحسب الإعدادات التلقائية، لن يعيد Firebase إرسال رسالة SMS جديدة إذا كان قد تم إرسالها مؤخرًا. يمكنك مع ذلك إلغاء هذا السلوك من خلال استدعاء طريقة verifyPhoneNumber التي تحتوي على رمز إعادة الإرسال المميز إلى الوسيطة forceResendingToken. في حال نجاح الإجراء، ستتم إعادة إرسال الرسالة القصيرة.

codeAutoRetrieval المضمّنة

على أجهزة Android التي تتيح الحل التلقائي لرمز الرسائل القصيرة SMS، سيتم استدعاء هذا المعالج إذا لم يحلّ الجهاز تلقائيًا رسالة SMS ضمن إطار زمني معيَّن. بعد مرور الإطار الزمني، لن يحاول الجهاز حلّ أي رسائل واردة بعد ذلك.

بشكلٍ تلقائي، ينتظر الجهاز لمدة 30 ثانية، ولكن يمكن تخصيص هذا الإعداد باستخدام الوسيطة timeout:

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  timeout: const Duration(seconds: 60),
  codeAutoRetrievalTimeout: (String verificationId) {
    // Auto-resolution timed out...
  },
);

الويب: signInWithPhoneNumber

على منصات الويب، يمكن للمستخدمين تسجيل الدخول من خلال تأكيد إمكانية وصولهم إلى الهاتف من خلال إدخال رمز الرسائل القصيرة SMS الذي تم إرساله إلى رقم الهاتف المقدّم. لتعزيز الأمان ومنع المحتوى غير المرغوب فيه، يُطلَب من المستخدمين إثبات هويتهم من خلال إكمال تطبيق Google reCAPTCHA المصغّر. بعد التأكيد، سيتم إرسال رمز الرسالة القصيرة SMS.

ستدير "حزمة تطوير البرامج (SDK) لمصادقة Firebase" في Flutter تطبيق reCAPTCHA المصغّر تلقائيًا، ولكن يمكنها التحكّم في كيفية عرضه وضبطه إذا لزم الأمر. للبدء، يمكنك الاتصال بطريقة signInWithPhoneNumber باستخدام رقم الهاتف.

FirebaseAuth auth = FirebaseAuth.instance;

// Wait for the user to complete the reCAPTCHA & for an SMS code to be sent.
ConfirmationResult confirmationResult = await auth.signInWithPhoneNumber('+44 7123 123 456');

سيؤدي استدعاء هذه الطريقة إلى عرض أداة reCAPTCHA أولاً. يجب على المستخدم إكمال الاختبار قبل إرسال رمز SMS. بعد إكمال هذه الخطوة، يمكنك تسجيل دخول المستخدم من خلال تقديم رمز الرسالة القصيرة SMS إلى طريقة confirm في استجابة ConfirmationResult التي تم حلها:

UserCredential userCredential = await confirmationResult.confirm('123456');

مثل مسارات تسجيل الدخول الأخرى، سيؤدي تسجيل الدخول الناجح إلى تشغيل جميع أدوات استماع حالة المصادقة التي اشتركت فيها من خلال تطبيقك.

إعدادات reCAPTCHA

تطبيق reCAPTCHA المصغّر هو عبارة عن عملية مُدارة بالكامل توفّر الأمان لتطبيق الويب الخاص بك.

تقبل الوسيطة الثانية لـ signInWithPhoneNumber مثيل RecaptchaVerifier اختياري يمكن استخدامه لإدارة الأداة. سيتم تلقائيًا عرض الأداة كأداة غير مرئية عند بدء عملية تسجيل الدخول. ستظهر أداة "غير مرئية" كنموذج بملء الصفحة في أعلى تطبيقك.

ومع ذلك، من الممكن عرض تطبيق مصغّر مضمَّن يجب على المستخدم الضغط عليه صراحةً لإثبات هويته.

لإضافة تطبيق مصغّر مضمَّن، حدِّد رقم تعريف عنصر DOM في الوسيطة container لمثيل RecaptchaVerifier. يجب أن يكون العنصر موجودًا وأن يكون فارغًا وإلا سيتم عرض خطأ. إذا لم يتم تقديم وسيطة container، سيتم عرض التطبيق المصغّر على أنّه "غير مرئي".

ConfirmationResult confirmationResult = await auth.signInWithPhoneNumber('+44 7123 123 456', RecaptchaVerifier(
  container: 'recaptcha',
  size: RecaptchaVerifierSize.compact,
  theme: RecaptchaVerifierTheme.dark,
));

يمكنك اختياريًا تغيير الحجم والمظهر عن طريق تخصيص الوسيطتين size وtheme كما هو موضّح أعلاه.

ويمكن أيضًا الاستماع إلى الأحداث، مثلاً ما إذا كان المستخدم قد أكمل اختبار reCAPTCHA، وما إذا كانت صلاحية reCAPTCHA قد انتهت أو حدث خطأ:

RecaptchaVerifier(
  onSuccess: () => print('reCAPTCHA Completed!'),
  onError: (FirebaseAuthException error) => print(error),
  onExpired: () => print('reCAPTCHA Expired!'),
);

الاختبار

يوفِّر Firebase الدعم للاختبارات المحلية لأرقام الهواتف:

  1. في "وحدة تحكُّم Firebase"، اختَر موفِّر مصادقة "الهاتف" وانقر على القائمة المنسدلة "أرقام الهاتف للاختبار".
  2. أدخِل رقم هاتف جديدًا (مثل +44 7444 555666) ورمزًا تجريبيًا (مثل 123456).

في حال تقديم رقم هاتف تجريبي إما للطريقة verifyPhoneNumber أو signInWithPhoneNumber، لن يتم فعليًا إرسال أي رسالة قصيرة. يمكنك بدلاً من ذلك تقديم رمز الاختبار مباشرةً إلى PhoneAuthProvider أو من خلال معالج نتائج تأكيد البيانات signInWithPhoneNumber.