المصادقة مع Firebase باستخدام رقم هاتف باستخدام JavaScript

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

أسهل طريقة لإضافة ميزة تسجيل الدخول باستخدام رقم الهاتف إلى تطبيقك هي استخدام FirebaseUI، الذي يتضمّن أداة تسجيل دخول جاهزة للاستخدام تنفّذ عمليات تسجيل الدخول باستخدام رقم الهاتف، بالإضافة إلى تسجيل الدخول المستند إلى كلمة المرور وتسجيل الدخول الموحّد. توضّح هذه المستندات كيفية تنفيذ عملية تسجيل الدخول باستخدام رقم الهاتف من خلال حزمة Firebase SDK.

قبل البدء

المخاوف المرتبطة بالأمان

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

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

تفعيل ميزة تسجيل الدخول باستخدام رقم الهاتف لمشروع Firebase

لتسجيل دخول المستخدمين عن طريق الرسائل القصيرة SMS، عليك أولاً تفعيل طريقة تسجيل الدخول باستخدام رقم الهاتف لمشروع Firebase:

1. في وحدة تحكّم Firebase، انتقِل إلى الأمان > المصادقة.
2. في علامة التبويب طريقة تسجيل الدخول ، فعِّل موفِّر تسجيل الدخول الهاتف.
3. اضبط سياسة بشأن المناطق التي تريد السماح بإرسال رسائل SMS إليها أو عدم السماح بذلك يمكن أن يساعد ضبط سياسة منطقة الرسائل القصيرة SMS في حماية تطبيقاتك من إساءة استخدام الرسائل القصيرة SMS. بالنسبة إلى المشاريع الجديدة، لا تسمح السياسة التلقائية بأي مناطق.
   1. في وحدة تحكّم Firebase، انتقِل إلى علامة التبويب الأمان > المصادقة > الإعدادات.
   2. في قسم سياسة منطقة الرسائل القصيرة SMS ، اضبط سياسة منطقة الرسائل القصيرة SMS.
4. إذا لم يسبق لك إجراء ذلك، عليك منح الإذن لنطاق تطبيقك:
   1. في وحدة تحكّم Firebase، انتقِل إلى علامة التبويب الأمان > المصادقة > الإعدادات.
   2. في قسم النطاقات المصرّح بها ، انقر على إضافة نطاق وأضِف نطاقك.

   يُرجى العِلم أنّه لا يُسمح باستخدام المضيف المحلي كنطاق مستضاف لأغراض المصادقة عبر الهاتف.

إعداد أداة التحقّق من reCAPTCHA

قبل أن تتمكّن من تسجيل دخول المستخدمين باستخدام أرقام هواتفهم، عليك إعداد أداة التحقّق من reCAPTCHA في Firebase. تستخدم Firebase خدمة reCAPTCHA لمنع إساءة الاستخدام، مثلاً من خلال التأكّد من أنّ طلب إثبات ملكية رقم الهاتف وارد من أحد النطاقات المسموح بها لتطبيقك.

لست بحاجة إلى إعداد عميل reCAPTCHA يدويًا. عند استخدام عنصر RecaptchaVerifier في Firebase SDK، تنشئ Firebase تلقائيًا أي مفاتيح ورموز سرية ضرورية للعميل وتتعامل معها.

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

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

import { getAuth } from "firebase/auth";

const auth = getAuth();
auth.languageCode = 'it';
// To apply the default browser preference instead of explicitly setting it.
// auth.useDeviceLanguage();
auth_set_language_code.js

firebase.auth().languageCode = 'it';
// To apply the default browser preference instead of explicitly setting it.
// firebase.auth().useDeviceLanguage();
index.js

استخدام شارة reCAPTCHA غير المرئية

لاستخدام شارة reCAPTCHA غير مرئية، أنشئ عنصر RecaptchaVerifier مع ضبط المعلمة size على invisible، مع تحديد رقم تعريف الزر الذي يرسِل نموذج تسجيل الدخول. على سبيل المثال:

import { getAuth, RecaptchaVerifier } from "firebase/auth";

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'sign-in-button', {
  'size': 'invisible',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    onSignInSubmit();
  }
});
auth_phone_recaptcha_verifier_invisible.js

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('sign-in-button', {
  'size': 'invisible',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    onSignInSubmit();
  }
});
phone-auth.js

استخدام أداة reCAPTCHA

لاستخدام أداة reCAPTCHA المرئية، أنشئ عنصرًا على صفحتك يحتوي على الأداة، ثم أنشئ عنصر RecaptchaVerifier، مع تحديد رقم تعريف الحاوية عند إجراء ذلك. على سبيل المثال:

import { getAuth, RecaptchaVerifier } from "firebase/auth";

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'recaptcha-container', {});
auth_phone_recaptcha_verifier_simple.js

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container');
phone-auth.js

اختياري: تحديد مَعلمات reCAPTCHA

يمكنك اختياريًا ضبط دوال رد الاتصال على عنصر RecaptchaVerifier التي يتم استدعاؤها عندما يحلّ المستخدم اختبار reCAPTCHA أو عندما تنتهي صلاحية reCAPTCHA قبل أن يرسِل المستخدم النموذج:

import { getAuth, RecaptchaVerifier } from "firebase/auth";

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'recaptcha-container', {
  'size': 'normal',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    // ...
  },
  'expired-callback': () => {
    // Response expired. Ask user to solve reCAPTCHA again.
    // ...
  }
});
auth_phone_recaptcha_verifier_visible.js

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container', {
  'size': 'normal',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    // ...
  },
  'expired-callback': () => {
    // Response expired. Ask user to solve reCAPTCHA again.
    // ...
  }
});
phone-auth.js

اختياري: العرض المسبق لـ reCAPTCHA

إذا أردت العرض المسبق لـ reCAPTCHA قبل إرسال طلب تسجيل الدخول، استدعِ الدالة render:

recaptchaVerifier.render().then((widgetId) => {
  window.recaptchaWidgetId = widgetId;
});
auth_phone_recaptcha_render.js

recaptchaVerifier.render().then((widgetId) => {
  window.recaptchaWidgetId = widgetId;
});
phone-auth.js

بعد أن يتم حلّ render، ستحصل على رقم تعريف أداة reCAPTCHA، الذي يمكنك استخدامه لإجراء طلبات إلى الـ reCAPTCHA API:

const recaptchaResponse = grecaptcha.getResponse(recaptchaWidgetId);
auth_get_recaptcha_response.js

const recaptchaResponse = grecaptcha.getResponse(recaptchaWidgetId);
phone-auth.js

إرسال رمز التحقّق إلى هاتف المستخدم

لبدء عملية تسجيل الدخول باستخدام رقم الهاتف، اعرض على المستخدم واجهة تطلب منه تقديم رقم هاتفه، ثم استدعِ الدالة signInWithPhoneNumber لطلب إرسال Firebase رمز مصادقة إلى هاتف المستخدم عن طريق الرسائل القصيرة SMS:

1. احصل على رقم هاتف المستخدم.

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

2. استدعِ الدالة signInWithPhoneNumber، مع تمرير رقم هاتف المستخدم وعنصر RecaptchaVerifier الذي أنشأته سابقًا.

   Web

   import { getAuth, signInWithPhoneNumber } from "firebase/auth";
   
   const phoneNumber = getPhoneNumberFromUserInput();
   const appVerifier = window.recaptchaVerifier;
   
   const auth = getAuth();
   signInWithPhoneNumber(auth, phoneNumber, appVerifier)
       .then((confirmationResult) => {
         // SMS sent. Prompt user to type the code from the message, then sign the
         // user in with confirmationResult.confirm(code).
         window.confirmationResult = confirmationResult;
         // ...
       }).catch((error) => {
         // Error; SMS not sent
         // ...
       });
   auth_phone_signin.js

   Web

   const phoneNumber = getPhoneNumberFromUserInput();
   const appVerifier = window.recaptchaVerifier;
   firebase.auth().signInWithPhoneNumber(phoneNumber, appVerifier)
       .then((confirmationResult) => {
         // SMS sent. Prompt user to type the code from the message, then sign the
         // user in with confirmationResult.confirm(code).
         window.confirmationResult = confirmationResult;
         // ...
       }).catch((error) => {
         // Error; SMS not sent
         // ...
       });
   phone-auth.js

   إذا أدّت الدالة signInWithPhoneNumber إلى حدوث خطأ، أعِد ضبط reCAPTCHA ليتمكّن المستخدم من المحاولة مرة أخرى:

   grecaptcha.reset(window.recaptchaWidgetId);
   
   // Or, if you haven't stored the widget ID:
   window.recaptchaVerifier.render().then(function(widgetId) {
     grecaptcha.reset(widgetId);
   });

تُرسِل طريقة signInWithPhoneNumber تحدّي reCAPTCHA إلى المستخدم، وإذا اجتاز المستخدم التحدّي، تطلب من Firebase Authentication إرسال رسالة قصيرة SMS تحتوي على رمز تحقّق إلى هاتف المستخدم.

تسجيل دخول المستخدم باستخدام رمز التحقّق

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

const code = getCodeFromUserInput();
confirmationResult.confirm(code).then((result) => {
  // User signed in successfully.
  const user = result.user;
  // ...
}).catch((error) => {
  // User couldn't sign in (bad verification code?)
  // ...
});
auth_phone_verify_code.js

const code = getCodeFromUserInput();
confirmationResult.confirm(code).then((result) => {
  // User signed in successfully.
  const user = result.user;
  // ...
}).catch((error) => {
  // User couldn't sign in (bad verification code?)
  // ...
});
phone-auth.js

إذا نجح استدعاء الدالة confirm، يتم تسجيل دخول المستخدم بنجاح.

الحصول على عنصر AuthCredential الوسيط

إذا كنت بحاجة إلى الحصول على عنصر AuthCredential لحساب المستخدم، مرِّر رمز التحقّق من نتيجة التأكيد ورمز التحقّق إلى PhoneAuthProvider.credential بدلاً من استدعاء confirm:

var credential = firebase.auth.PhoneAuthProvider.credential(confirmationResult.verificationId, code);

بعد ذلك، يمكنك تسجيل دخول المستخدم باستخدام بيانات الاعتماد:

firebase.auth().signInWithCredential(credential);

الاختبار باستخدام أرقام هواتف وهمية

يمكنك إعداد أرقام هواتف وهمية للتطوير باستخدام الـ Firebase وحدة تحكّم. يوفر الاختبار باستخدام أرقام هواتف وهمية المزايا التالية:

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

يجب أن تستوفي أرقام الهواتف الوهمية المتطلبات التالية:

1. تأكَّد من استخدام أرقام هواتف وهمية بالفعل وغير موجودة حاليًا. Firebase Authentication لا تسمح لك بضبط أرقام الهواتف الحالية التي يستخدمها مستخدمون حقيقيون كأرقام اختبار. أحد الخيارات هو استخدام أرقام مسبوقة بالرقم 555 كأرقام هواتف اختبار في الولايات المتحدة، على سبيل المثال: +1 650-555-3434
2. يجب تنسيق أرقام الهواتف بشكلٍ صحيح من حيث الطول والقيود الأخرى ستظل تخضع لعملية التحقّق نفسها التي يخضع لها رقم هاتف المستخدم الحقيقي.
3. يمكنك إضافة ما يصل إلى 10 أرقام هواتف للتطوير.
4. استخدِم أرقام هواتف/رموز اختبار يصعب تخمينها وغيِّر ها بشكلٍ متكرّر.

إنشاء أرقام هواتف وهمية ورموز تحقّق

1. في وحدة تحكّم Firebase، انتقِل إلى الأمان > المصادقة.
2. في علامة التبويب طريقة تسجيل الدخول ، فعِّل موفِّر تسجيل الدخول الهاتف إذا لم يسبق لك إجراء ذلك.
3. وسِّع قسم أرقام الهواتف للاختبار.
4. قدِّم رقم الهاتف الذي تريد اختباره، على سبيل المثال: +1 650-555-3434.
5. قدِّم رمز التحقّق المكوّن من 6 أرقام لهذا الرقم تحديدًا، على سبيل المثال: 654321.
6. انقر على إضافة لكل رقم. إذا لزم الأمر، يمكنك حذف رقم الهاتف والرمز الخاص به من خلال تمرير مؤشر الماوس فوق الصف المقابل والنقر على رمز سلة المهملات

الاختبار اليدوي

يمكنك البدء مباشرةً باستخدام رقم هاتف وهمي في تطبيقك. يسمح لك ذلك بإجراء اختبار يدوي أثناء مراحل التطوير بدون مواجهة مشاكل في الحصة أو التقييد. يمكنك أيضًا إجراء الاختبار مباشرةً من محاكي iOS أو محاكي Android بدون تثبيت "خدمات Google Play".

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

عند إكمال عملية تسجيل الدخول، يتم إنشاء مستخدم Firebase باستخدام رقم الهاتف هذا. يتّسم المستخدم بالسلوك والخصائص نفسها التي يتّسم بها مستخدم رقم الهاتف الحقيقي، ويمكنه الوصول إلى Realtime Database/Cloud Firestore والخدمات الأخرى بالطريقة نفسها. تحمل رمز تعريف المستخدم الذي تم إنشاؤه أثناء هذه العملية التوقيع نفسه الذي يحمله مستخدم رقم الهاتف الحقيقي.

هناك خيار آخر وهو ضبط دور اختبار من خلال المطالبات المخصّصة لهؤلاء المستخدمين لتمييزهم كمستخدمين وهميين إذا أردت زيادة تقييد الوصول.

اختبار التكامل

بالإضافة إلى الاختبار اليدوي، توفّر Firebase Authentication واجهات برمجة تطبيقات للمساعدة في كتابة اختبارات التكامل لاختبار ميزة المصادقة عبر الهاتف. تؤدي واجهات برمجة التطبيقات هذه إلى إيقاف ميزة التحقّق من التطبيق من خلال إيقاف متطلبات reCAPTCHA في الإشعارات المنبثقة على الويب والإشعارات المنبثقة الصامتة على iOS. يسمح ذلك بإجراء اختبارات تلقائية في عمليات تسجيل الدخول هذه ويسهّل تنفيذها. بالإضافة إلى ذلك، تساعد في توفير إمكانية اختبار عمليات التحقّق الفوري على Android.

على الويب، اضبط appVerificationDisabledForTesting على true قبل عرض firebase.auth.RecaptchaVerifier. يؤدي ذلك إلى حلّ اختبار reCAPTCHA تلقائيًا، ما يسمح لك بتمرير رقم الهاتف بدون حلّه يدويًا. يُرجى العِلم أنّه حتى إذا تم إيقاف reCAPTCHA، سيظل تسجيل الدخول باستخدام رقم هاتف غير وهمي غير مكتمل. لا يمكن استخدام هذه الواجهة إلا مع أرقام الهواتف الوهمية.

// Turn off phone auth app verification.
firebase.auth().settings.appVerificationDisabledForTesting = true;

var phoneNumber = "+16505554567";
var testVerificationCode = "123456";

// This will render a fake reCAPTCHA as appVerificationDisabledForTesting is true.
// This will resolve after rendering without app verification.
var appVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container');
// signInWithPhoneNumber will call appVerifier.verify() which will resolve with a fake
// reCAPTCHA response.
firebase.auth().signInWithPhoneNumber(phoneNumber, appVerifier)
    .then(function (confirmationResult) {
      // confirmationResult can resolve with the fictional testVerificationCode above.
      return confirmationResult.confirm(testVerificationCode)
    }).catch(function (error) {
      // Error; SMS not sent
      // ...
    });

تختلف طريقة عمل أدوات التحقّق من التطبيق في reCAPTCHA الوهمي المرئي وغير المرئي عندما يتم إيقاف ميزة التحقّق من التطبيق:

• reCAPTCHA المرئي: عند عرض reCAPTCHA المرئي من خلال appVerifier.render()، يتم حله تلقائيًا بعد جزء من الثانية. يعادل ذلك نقر المستخدم على reCAPTCHA فور عرضه. ستنتهي صلاحية استجابة reCAPTCHA بعد فترة من الوقت، ثم سيتم حلّها تلقائيًا مرة أخرى.
• شارة reCAPTCHA غير مرئية: لا يتم حلّ شارة reCAPTCHA غير المرئية تلقائيًا عند عرضها، بل يتم ذلك عند appVerifier.verify()الاستدعاء أو عند النقر على رابط الزر في reCAPTCHA بعد جزء من الثانية. وبالمثل، ستنتهي صلاحية الاستجابة بعد فترة من الوقت ولن يتم حلّها تلقائيًا إلا بعد استدعاء appVerifier.verify() أو عند النقر على رابط الزر في reCAPTCHA مرة أخرى.

عند حلّ اختبار reCAPTCHA وهمي، يتم تفعيل دالة رد الاتصال المقابلة كما هو متوقّع باستخدام الاستجابة الوهمية. إذا تم تحديد دالة رد اتصال لانتهاء الصلاحية أيضًا، سيتم تفعيلها عند انتهاء الصلاحية.

الخطوات التالية

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

• في تطبيقاتك، الطريقة المقترَحة لمعرفة حالة مصادقة المستخدم هي ضبط مراقب على عنصر Auth. بعد ذلك، يمكنك الحصول على معلومات الملف الشخصي الأساسية للمستخدم من عنصر User. يمكنك الاطّلاع على إدارة المستخدمين.

• في Firebase Realtime Database وCloud Storage قواعد الأمان، يمكنك الحصول على رقم تعريف المستخدم الفريد للمستخدم الذي سجّل الدخول من متغيّر auth، واستخدامه للتحكّم في البيانات التي يمكن للمستخدم الوصول إليها.

يمكنك السماح للمستخدمين بتسجيل الدخول إلى تطبيقك باستخدام عدة موفّري مصادقة من خلال ربط بيانات اعتماد موفِّر المصادقة بحساب مستخدم حالي.

لتسجيل خروج مستخدم، استدعِ signOut:

import { getAuth, signOut } from "firebase/auth";

const auth = getAuth();
signOut(auth).then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
auth_sign_out.js

firebase.auth().signOut().then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
index.js