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

الاستخدام

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

verificationCompleted

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

عندما يتم تسليم رمز SMS إلى الجهاز، سيتأكّد نظام التشغيل 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).

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