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

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

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

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

الإعداد

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

1. في وحدة تحكّم Firebase، انتقِل إلى الأمان > المصادقة.

2. في علامة التبويب طريقة تسجيل الدخول ، فعِّل موفّر تسجيل الدخول الهاتف.

3. اضبط المتطلبات الخاصة بالمنصة:

   • iOS+‎: في Xcode، فعِّل الإشعارات الفورية لمشروعك وتأكَّد من ضبط مفتاح مصادقة APNs باستخدام خدمة المراسلة عبر السحابة الإلكترونية من Firebase (FCM). بالإضافة إلى ذلك، عليك تفعيل أوضاع الخلفية للإشعارات عن بُعد.

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

   • Android: حدِّد الملف المرجعي SHA-1 لتطبيقك إذا لم يسبق لك إجراء ذلك:

     1. في وحدة تحكّم Firebase، انتقِل إلى علامة التبويب الإعدادات > الإعدادات العامة.

     2. انتقِل للأسفل إلى بطاقة تطبيقاتك ، واختَر تطبيق Android، وأضِف الملف المرجعي SHA-1 في حقل الملفات المرجعية لشهادة SHA.

     لمعرفة التفاصيل حول كيفية الحصول على الملف المرجعي SHA لتطبيقك، يُرجى الاطّلاع على مقالة مصادقة العميل.

   • الويب: فوِّض نطاق تطبيقك إذا لم يسبق لك إجراء ذلك:

     1. في وحدة تحكّم Firebase، انتقِل إلى علامة التبويب الأمان> المصادقة > الإعدادات.

     2. في قسم النطاقات المفوَّضة ، انقر على إضافة نطاق ، وأضِف نطاقك.

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

الاستخدام

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

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

المنصة الأصلية: verifyPhoneNumber

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

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

await FirebaseAuth.instance.verifyPhoneNumber(
  phoneNumber: '[phone]',
  verificationCompleted: (PhoneAuthCredential credential) {},
  verificationFailed: (FirebaseAuthException e) {},
  codeSent: (String verificationId, int? resendToken) {},
  codeAutoRetrievalTimeout: (String verificationId) {},
);

ملاحظة: استنادًا إلى خطة الفوترة، قد يتم فرض حدّ أقصى يومي على عدد رسائل SMS المُرسَلة. يُرجى الاطّلاع على الحدود في "مصادقة Firebase".

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

1. verificationCompleted: المعالجة التلقائية لرمز الرسالة القصيرة (SMS) على أجهزة Android
2. verificationFailed: معالجة أحداث الفشل، مثل أرقام الهواتف غير الصالحة أو تجاوز الحدّ الأقصى لعدد الرسائل القصيرة (SMS)
3. codeSent: معالجة الحالات التي يتم فيها إرسال رمز إلى الجهاز من Firebase، ويُستخدم هذا الرمز لطلب إدخاله من المستخدمين
4. codeAutoRetrievalTimeout: معالجة انتهاء المهلة في حال تعذُّر المعالجة التلقائية لرمز الرسالة القصيرة (SMS)

verificationCompleted

لن يتم استدعاء معالج الأحداث هذا إلا على أجهزة Android التي تتيح حلّ رمز الرسالة القصيرة (SMS) تلقائيًا.

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

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '[phone]',
  verificationCompleted: (PhoneAuthCredential credential) async {
    // ANDROID ONLY!

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

verificationFailed

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

FirebaseAuth auth = FirebaseAuth.instance;

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

    // Handle other errors
  },
);

codeSent

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

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

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '[phone]',
  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 التي تتيح حلّ رمز الرسالة القصيرة (SMS) تلقائيًا، سيتم استدعاء معالج الأحداث هذا إذا لم يتم حلّ رمز الرسالة القصيرة (SMS) تلقائيًا خلال فترة زمنية معيّنة. بعد انقضاء الفترة الزمنية، لن يحاول الجهاز حلّ أي رسائل واردة.

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

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '[phone]',
  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('[phone]');

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

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

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

إعداد reCAPTCHA

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

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

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

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

ConfirmationResult confirmationResult = await auth.signInWithPhoneNumber('[phone]', 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. أدخِل رقم هاتف جديدًا (مثل [phone]) ورمز اختبار (مثل 123456).

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