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

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

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

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

يثبت

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

  1. تمكين الهاتف كطريقة لتسجيل الدخول في وحدة تحكم Firebase .
  2. Android : إذا لم تكن قد قمت بالفعل بتعيين تجزئة SHA-1 لتطبيقك في وحدة تحكم Firebase ، فافعل ذلك. راجع مصادقة عميلك للحصول على معلومات حول العثور على تجزئة SHA-1 لتطبيقك.
  3. iOS : في Xcode، قم بتمكين الإشعارات المباشرة لمشروعك وتأكد من تكوين مفتاح مصادقة APNs الخاص بك باستخدام Firebase Cloud Messaging (FCM) . بالإضافة إلى ذلك، يجب عليك تمكين أوضاع الخلفية للإشعارات عن بعد. لعرض شرح متعمق لهذه الخطوة، راجع وثائق Firebase iOS Phone Auth .
  4. الويب : تأكد من إضافة مجال التطبيقات الخاص بك على وحدة تحكم Firebase ، ضمن مجالات إعادة توجيه OAuth .

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

الاستخدام

توفر Firebase Authentication SDK for 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. اكتمل التحقق : المعالجة التلقائية لرمز الرسائل القصيرة على أجهزة Android.
  2. فشل التحقق : التعامل مع أحداث الفشل مثل أرقام الهواتف غير الصالحة أو ما إذا تم تجاوز حصة الرسائل النصية القصيرة.
  3. codeSent : التعامل مع إرسال رمز إلى الجهاز من Firebase، ويستخدم لمطالبة المستخدمين بإدخال الرمز.
  4. codeAutoRetrievalTimeout : التعامل مع المهلة الزمنية التي تفشل فيها المعالجة التلقائية لرمز الرسائل القصيرة.

اكتمل التحقق

سيتم استدعاء هذا المعالج فقط على أجهزة Android التي تدعم الدقة التلقائية لرمز الرسائل القصيرة.

عندما يتم تسليم رمز الرسائل القصيرة إلى الجهاز، سيتحقق Android تلقائيًا من رمز الرسائل القصيرة دون مطالبة المستخدم بإدخال الرمز يدويًا. في حالة حدوث هذا الحدث، يتم توفير 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 ).

بمجرد تشغيله، سيكون الوقت مناسبًا لتحديث واجهة مستخدم التطبيق الخاص بك لمطالبة المستخدم بإدخال رمز الرسائل القصيرة الذي يتوقعه. بمجرد إدخال رمز الرسائل القصيرة، يمكنك دمج معرف التحقق مع رمز الرسائل القصيرة لإنشاء 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 . في حالة النجاح، سيتم إعادة إرسال الرسالة النصية القصيرة.

codeAutoRetrievalTimeout

على أجهزة Android التي تدعم التحليل التلقائي لرمز الرسائل القصيرة، سيتم استدعاء هذا المعالج إذا لم يقم الجهاز بحل رسالة 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

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

ستقوم حزمة Firebase Authentication SDK لـ 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. بمجرد الانتهاء، يمكنك بعد ذلك تسجيل دخول المستخدم عن طريق توفير رمز الرسائل القصيرة لطريقة confirm في استجابة ConfirmationResult التي تم حلها:

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

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

تكوين ريكابتشا

أداة 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 Console، حدد موفر مصادقة "الهاتف" وانقر على القائمة المنسدلة "أرقام الهواتف للاختبار".
  2. أدخل رقم هاتف جديد (على سبيل المثال +44 7444 555666 ) ورمز اختبار (على سبيل المثال 123456 ).

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