إضافة بيانات تسجيل الدخول بسهولة إلى تطبيق الويب باستخدام FirebaseUI

FirebaseUI هي مكتبة تم إنشاؤها على قمة حزمة تطوير البرامج (SDK) لميزة "المصادقة في Firebase"، وهي توفّر مسارات واجهة مستخدم قابلة للاستخدام في تطبيقك. توفّر FirebaseUI المزايا التالية:

  • مزوّدو خدمة متعدّدون: مسارات تسجيل الدخول باستخدام عنوان البريد الإلكتروني/كلمة المرور، ورابط البريد الإلكتروني، و مصادقة الهاتف، وتسجيل الدخول إلى Google وFacebook وTwitter وGitHub
  • ربط الحساب: عمليات لربط حسابات المستخدمين بأمان على مستوى مقدّمي خدمات ملف التعريف
  • التخصيص: يمكنك إلغاء أنماط CSS في FirebaseUI لمطابقة متطلبات تطبيقك. وبما أنّ FirebaseUI مفتوح المصدر، يمكنك أيضًا إنشاء نسخة من المشروع وتخصيصه وفقًا لاحتياجاتك.
  • إنشاء حساب أو تسجيل الدخول بنقرة واحدة: يمكنك الدمج التلقائي مع إنشاء حساب بنقرة واحدة لتسجيل الدخول بسرعة على جميع الأجهزة.
  • واجهة مستخدم مترجَمة: إتاحة التطبيق على مستوى أكثر من 40 لغة
  • ترقية المستخدمين المجهولين: تتيح هذه الميزة ترقية المستخدمين المجهولين من خلال تسجيل الدخول أو الاشتراك. لمزيد من المعلومات، يُرجى الانتقال إلى قسم "ترقية المستخدمين المجهولين".

قبل البدء

  1. أضِف Firebase Authentication إلى تطبيق الويب، مع التأكّد من استخدام واجهة برمجة التطبيقات ذات النطاق المعيّن للإصدار 9 أو الإصدارات الأحدث (وليس واجهة برمجة التطبيقات المكوّنة من وحدات، راجِع الشريط الجانبي أعلاه).

  2. أدرِج FirebaseUI من خلال أحد الخيارَين التاليَين:

    1. شبكة توصيل المحتوى (CDN)

      أدرِج النص البرمجي وملف CSS التاليَين في علامة <head> لصفحتك، أسفل مقتطف الإعداد من وحدة تحكّم Firebase:

      <script src="https://www.gstatic.com/firebasejs/ui/6.0.1/firebase-ui-auth.js"></script>
<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/firebasejs/ui/6.0.1/firebase-ui-auth.css" />

    2. وحدة npm

      ثبِّت FirebaseUI وتبعياتها من خلال npm باستخدام العبارة التالية:

      $ npm install firebaseui --save

      require الوحدات التالية ضمن ملفات المصدر:

      var firebase = require('firebase');
var firebaseui = require('firebaseui');

    3. مكوّن Bower

      ثبِّت FirebaseUI ومستلزماتها من خلال Bower باستخدام العبارة التالية:

      $ bower install firebaseui --save

      أدرِج الملفات المطلوبة في ملف HTML، إذا كان خادم HTTP يعرض الملفات ضمن bower_components/:

      <script src="bower_components/firebaseui/dist/firebaseui.js"></script>
<link type="text/css" rel="stylesheet" href="bower_components/firebaseui/dist/firebaseui.css" />

بدء FirebaseUI

بعد استيراد حزمة تطوير البرامج (SDK)، عليك إعداد واجهة مستخدم المصادقة.

// Initialize the FirebaseUI Widget using Firebase.
var ui = new firebaseui.auth.AuthUI(firebase.auth());

إعداد طُرق تسجيل الدخول

قبل أن تتمكّن من استخدام Firebase لتسجيل دخول المستخدمين، عليك تفعيل وضبط طرق تسجيل الدخول التي تريد دعمها.

عنوان البريد الإلكتروني وكلمة المرور

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

  2. أضِف رقم تعريف موفِّر خدمة البريد الإلكتروني إلى قائمة signInOptions FirebaseUI.

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    firebase.auth.EmailAuthProvider.PROVIDER_ID
  ],
  // Other config options...
});

  3. اختياري: يمكن ضبط EmailAuthProvider لطلب من المستخدم إدخال اسم معروض (يتم ضبطه تلقائيًا على true).

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    {
      provider: firebase.auth.EmailAuthProvider.PROVIDER_ID,
      requireDisplayName: false
    }
  ]
});

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

  2. في القسم نفسه، فعِّل رابط البريد الإلكتروني (تسجيل الدخول بدون كلمة مرور)، ثم انقر على حفظ.

  3. أضِف معرّف مقدّم خدمة البريد الإلكتروني إلى قائمة FirebaseUI signInOptions مع رابط البريد الإلكتروني signInMethod.

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    {
      provider: firebase.auth.EmailAuthProvider.PROVIDER_ID,
      signInMethod: firebase.auth.EmailAuthProvider.EMAIL_LINK_SIGN_IN_METHOD
    }
  ],
  // Other config options...
});

  4. عند عرض واجهة مستخدم تسجيل الدخول بشكل مشروط (ملائم للتطبيقات المكوّنة من صفحة واحدة)، استخدِم ui.isPendingRedirect() لرصد ما إذا كان عنوان URL يتوافق مع تسجيل الدخول باستخدام رابط البريد الإلكتروني ويجب عرض واجهة المستخدم لإكمال عملية تسجيل الدخول.

    // Is there an email link sign-in?
if (ui.isPendingRedirect()) {
  ui.start('#firebaseui-auth-container', uiConfig);
}
// This can also be done via:
if (firebase.auth().isSignInWithEmailLink(window.location.href)) {
  ui.start('#firebaseui-auth-container', uiConfig);
}

  5. اختياري: يمكن ضبط EmailAuthProvider لتسجيل الدخول باستخدام رابط البريد الإلكتروني للسماح للمستخدم بإكمال عملية تسجيل الدخول على جميع الأجهزة أو حظره من ذلك.

    يمكن تحديد دالة emailLinkSignIn اختيارية لردّ القيمة الخاصة بالإعدادات firebase.auth.ActionCodeSettings المطلوب استخدامها عند إرسال الرابط. يتيح ذلك تحديد كيفية التعامل مع الرابط والرابط الديناميكي المخصّص والحالة الإضافية في الرابط لصفحة في التطبيق وما إلى ذلك. وفي حال عدم تقديمه، يتم استخدام عنوان URL الحالي ويتم بدء مسار ويب فقط.

    إنّ ميزة تسجيل الدخول باستخدام رابط البريد الإلكتروني في FirebaseUI-web متوافقة مع FirebaseUI-Android و FirebaseUI-iOS حيث يمكن لمستخدم واحد يبدأ العملية من FirebaseUI-Android فتح الرابط وإكمال عملية تسجيل الدخول باستخدام FirebaseUI-web. وينطبق الأمر نفسه على مسار التنقّل العكسي.

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    {
      provider: firebase.auth.EmailAuthProvider.PROVIDER_ID,
      signInMethod: firebase.auth.EmailAuthProvider.EMAIL_LINK_SIGN_IN_METHOD,
      // Allow the user the ability to complete sign-in cross device,
      // including the mobile apps specified in the ActionCodeSettings
      // object below.
      forceSameDevice: false,
      // Used to define the optional firebase.auth.ActionCodeSettings if
      // additional state needs to be passed along request and whether to open
      // the link in a mobile app if it is installed.
      emailLinkSignIn: function() {
        return {
          // Additional state showPromo=1234 can be retrieved from URL on
          // sign-in completion in signInSuccess callback by checking
          // window.location.href.
          url: 'https://www.example.com/completeSignIn?showPromo=1234',
          // Custom FDL domain.
          dynamicLinkDomain: 'example.page.link',
          // Always true for email link sign-in.
          handleCodeInApp: true,
          // Whether to handle link in iOS app if installed.
          iOS: {
            bundleId: 'com.example.ios'
          },
          // Whether to handle link in Android app if opened in an Android
          // device.
          android: {
            packageName: 'com.example.android',
            installApp: true,
            minimumVersion: '12'
          }
        };
      }
    }
  ]
});

موفّرو OAuth (Google وFacebook وTwitter وGitHub)

  1. في وحدة تحكّم Firebase، افتح قسم المصادقة وفعِّل تسجيل الدخول المُحدَّد لموفّر OAuth. تأكَّد أيضًا من تحديد معرّف العميل وسر العميل المرتبطَين ببروتوكول OAuth.

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

  3. أضِف رقم تعريف موفِّر OAuth إلى قائمة signInOptions FirebaseUI.

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    // List of OAuth providers supported.
    firebase.auth.GoogleAuthProvider.PROVIDER_ID,
    firebase.auth.FacebookAuthProvider.PROVIDER_ID,
    firebase.auth.TwitterAuthProvider.PROVIDER_ID,
    firebase.auth.GithubAuthProvider.PROVIDER_ID
  ],
  // Other config options...
});

  4. اختياري: لتحديد نطاقات مخصّصة أو مَعلمات OAuth مخصّصة لكل مقدّم خدمة، يمكنك تمرير عنصر بدلاً من قيمة مقدّم الخدمة فقط:

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    {
      provider: firebase.auth.GoogleAuthProvider.PROVIDER_ID,
      scopes: [
        'https://www.googleapis.com/auth/contacts.readonly'
      ],
      customParameters: {
        // Forces account selection even when one account
        // is available.
        prompt: 'select_account'
      }
    },
    {
      provider: firebase.auth.FacebookAuthProvider.PROVIDER_ID,
      scopes: [
        'public_profile',
        'email',
        'user_likes',
        'user_friends'
      ],
      customParameters: {
        // Forces password re-entry.
        auth_type: 'reauthenticate'
      }
    },
    firebase.auth.TwitterAuthProvider.PROVIDER_ID, // Twitter does not support scopes.
    firebase.auth.EmailAuthProvider.PROVIDER_ID // Other providers don't need to be given as object.
  ]
});

رقم الهاتف

  1. في وحدة تحكّم Firebase، افتح قسم المصادقة وفعِّل تسجيل الدخول باستخدام رقم الهاتف.

  2. تأكَّد أيضًا من أنّ النطاق الذي سيتم عرض صفحة تسجيل الدخول عليه تمت إضافته إلى قائمة النطاقات المعتمَدة.

  3. أضِف معرّف مقدّم خدمة رقم الهاتف إلى قائمة signInOptions في FirebaseUI.

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    firebase.auth.PhoneAuthProvider.PROVIDER_ID
  ],
  // Other config options...
});

  4. اختياري: يمكن ضبط PhoneAuthProvider باستخدام مَعلمات reCAPTCHA مخصّصة سواء كانت شارة reCAPTCHA مرئية أو غير مرئية (الإعداد التلقائي هو الوضع العادي). يُرجى الاطّلاع على مستندات واجهة برمجة تطبيقات reCAPTCHA لمزيد من التفاصيل.

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

    تتوفّر الخيارات التالية حاليًا.

    ui.start('#firebaseui-auth-container', {
  signInOptions: [
    {
      provider: firebase.auth.PhoneAuthProvider.PROVIDER_ID,
      recaptchaParameters: {
        type: 'image', // 'audio'
        size: 'normal', // 'invisible' or 'compact'
        badge: 'bottomleft' //' bottomright' or 'inline' applies to invisible.
      },
      defaultCountry: 'GB', // Set default country to the United Kingdom (+44).
      // For prefilling the national number, set defaultNationNumber.
      // This will only be observed if only phone Auth provider is used since
      // for multiple providers, the NASCAR screen will always render first
      // with a 'sign in with phone number' button.
      defaultNationalNumber: '1234567890',
      // You can also pass the full phone number string instead of the
      // 'defaultCountry' and 'defaultNationalNumber'. However, in this case,
      // the first country ID that matches the country code will be used to
      // populate the country selector. So for countries that share the same
      // country code, the selected country may not be the expected one.
      // In that case, pass the 'defaultCountry' instead to ensure the exact
      // country is selected. The 'defaultCountry' and 'defaultNationaNumber'
      // will always have higher priority than 'loginHint' which will be ignored
      // in their favor. In this case, the default country will be 'GB' even
      // though 'loginHint' specified the country code as '+1'.
      loginHint: '+11234567890'
    }
  ]
});

تسجيل الدخول

لبدء عملية تسجيل الدخول في FirebaseUI، عليك إعداد مثيل FirebaseUI من خلال تمرير مثيل Auth الأساسي.

// Initialize the FirebaseUI Widget using Firebase.
var ui = new firebaseui.auth.AuthUI(firebase.auth());

حدِّد عنصر HTML الذي سيتم عرض التطبيق المصغّر لتسجيل الدخول في FirebaseUI عليه.

<!-- The surrounding HTML is left untouched by FirebaseUI.
     Your app may use that space for branding, controls and other customizations.-->
<h1>Welcome to My Awesome App</h1>
<div id="firebaseui-auth-container"></div>
<div id="loader">Loading...</div>

حدِّد إعدادات FirebaseUI (مزوّدي الخدمة المتوافقين وتخصيصات واجهة المستخدم بالإضافة إلى وظائف الاستدعاء عند النجاح وما إلى ذلك).

var uiConfig = {
  callbacks: {
    signInSuccessWithAuthResult: function(authResult, redirectUrl) {
      // User successfully signed in.
      // Return type determines whether we continue the redirect automatically
      // or whether we leave that to developer to handle.
      return true;
    },
    uiShown: function() {
      // The widget is rendered.
      // Hide the loader.
      document.getElementById('loader').style.display = 'none';
    }
  },
  // Will use popup for IDP Providers sign-in flow instead of the default, redirect.
  signInFlow: 'popup',
  signInSuccessUrl: '<url-to-redirect-to-on-success>',
  signInOptions: [
    // Leave the lines as is for the providers you want to offer your users.
    firebase.auth.GoogleAuthProvider.PROVIDER_ID,
    firebase.auth.FacebookAuthProvider.PROVIDER_ID,
    firebase.auth.TwitterAuthProvider.PROVIDER_ID,
    firebase.auth.GithubAuthProvider.PROVIDER_ID,
    firebase.auth.EmailAuthProvider.PROVIDER_ID,
    firebase.auth.PhoneAuthProvider.PROVIDER_ID
  ],
  // Terms of service url.
  tosUrl: '<your-tos-url>',
  // Privacy policy url.
  privacyPolicyUrl: '<your-privacy-policy-url>'
};

أخيرًا، يمكنك عرض واجهة FirebaseUI Auth:

// The start method will wait until the DOM is loaded.
ui.start('#firebaseui-auth-container', uiConfig);

ترقية المستخدمين المجهولين

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

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

التعامل مع تعارضات دمج ترقية المستخدم المجهول

هناك حالات يحاول فيها مستخدم سجّل الدخول في البداية بشكل مجهول الترقية إلى مستخدم حالي على Firebase. بما أنّه لا يمكن ربط مستخدم حالي بمستخدم حالي آخر، ستُشغِّل FirebaseUI دالة الاستدعاء signInFailure مع رمز الخطأ firebaseui/anonymous-upgrade-merge-conflict عند حدوث ما سبق. سيحتوي عنصر الخطأ أيضًا على بيانات الاعتماد الدائمة. يجب بدء تسجيل الدخول باستخدام بيانات الاعتماد الدائمة في ردّ الاتصال لإكمال عملية تسجيل الدخول. قبل اكتمال عملية تسجيل الدخول من خلال auth.signInWithCredential(error.credential)، عليك حفظ بيانات المستخدِم المجهول وحذفه. بعد إكمال عملية تسجيل الدخول، انسخ البيانات مرة أخرى إلى المستخدم غير المجهول الهوية. يوضّح المثال أدناه آلية عمل هذه العملية.

// Temp variable to hold the anonymous user data if needed.
var data = null;
// Hold a reference to the anonymous current user.
var anonymousUser = firebase.auth().currentUser;
ui.start('#firebaseui-auth-container', {
  // Whether to upgrade anonymous users should be explicitly provided.
  // The user must already be signed in anonymously before FirebaseUI is
  // rendered.
  autoUpgradeAnonymousUsers: true,
  signInSuccessUrl: '<url-to-redirect-to-on-success>',
  signInOptions: [
    firebase.auth.GoogleAuthProvider.PROVIDER_ID,
    firebase.auth.FacebookAuthProvider.PROVIDER_ID,
    firebase.auth.EmailAuthProvider.PROVIDER_ID,
    firebase.auth.PhoneAuthProvider.PROVIDER_ID
  ],
  callbacks: {
    // signInFailure callback must be provided to handle merge conflicts which
    // occur when an existing credential is linked to an anonymous user.
    signInFailure: function(error) {
      // For merge conflicts, the error.code will be
      // 'firebaseui/anonymous-upgrade-merge-conflict'.
      if (error.code != 'firebaseui/anonymous-upgrade-merge-conflict') {
        return Promise.resolve();
      }
      // The credential the user tried to sign in with.
      var cred = error.credential;
      // Copy data from anonymous user to permanent user and delete anonymous
      // user.
      // ...
      // Finish sign-in after data is copied.
      return firebase.auth().signInWithCredential(cred);
    }
  }
});

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

  • لمزيد من المعلومات عن استخدام FirebaseUI وتخصيصه، يُرجى الانتقال إلى ملف README.
  • إذا واجهت مشكلة في FirebaseUI وأردت الإبلاغ عنها، استخدِم أداة تتبُّع المشاكل في GitHub.