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

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

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

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

الإعداد

قبل البدء في استخدام ميزة "المصادقة عبر الهاتف"، تأكَّد من اتّباع الخطوات التالية:

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

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

الاستخدام

توفّر حزمة تطوير البرامج (SDK) لخدمة Firebase Authentication في 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. ‫verificationCompleted: معالجة رمز الرسالة القصيرة تلقائيًا على أجهزة Android
2. verificationFailed: للتعامل مع أحداث الأعطال، مثل أرقام الهواتف غير الصالحة أو ما إذا تم تجاوز حصة الرسائل القصيرة.
3. codeSent: يتم استخدامه عند إرسال رمز إلى الجهاز من Firebase، ويُستخدَم لطلب إدخال الرمز من المستخدمين.
4. codeAutoRetrievalTimeout: للتعامل مع انتهاء المهلة عند تعذُّر معالجة رمز SMS تلقائيًا.

verificationCompleted

لن يتم استدعاء معالج الأحداث هذا إلا على أجهزة 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);
  },
);

verificationFailed

إذا عرضت Firebase خطأً، مثلاً بسبب رقم هاتف غير صحيح أو إذا تم تجاوز حصة الرسائل القصيرة للمشروع، سيتم إرسال 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
  },
);

codeSent

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

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

codeAutoRetrievalTimeout

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

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

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