با FirebaseUI به راحتی ورود به برنامه وب خود را اضافه کنید

FirebaseUI کتابخانه‌ای است که بر پایه‌ی SDK احراز هویت فایربیس ساخته شده و جریان‌های رابط کاربری drop-in را برای استفاده در برنامه‌ی شما فراهم می‌کند. FirebaseUI مزایای زیر را ارائه می‌دهد:

  • ارائه دهندگان متعدد - جریان‌های ورود به سیستم برای ایمیل/رمز عبور، لینک ایمیل، احراز هویت تلفنی، ورود به سیستم از طریق گوگل، فیسبوک، توییتر و گیت‌هاب.
  • پیوند حساب - جریان‌ها برای پیوند ایمن حساب‌های کاربری در بین ارائه‌دهندگان هویت.
  • شخصی‌سازی - استایل‌های CSS مربوط به FirebaseUI را برای مطابقت با نیازهای برنامه خود، بازنویسی کنید. همچنین، از آنجا که FirebaseUI متن‌باز است، می‌توانید پروژه را تغییر داده و دقیقاً مطابق با نیازهای خود سفارشی کنید.
  • ثبت نام با یک لمس و ورود خودکار - ادغام خودکار با ثبت نام با یک لمس برای ورود سریع بین دستگاه‌های مختلف.
  • رابط کاربری بومی‌سازی شده - بین‌المللی‌سازی برای بیش از ۴۰ زبان .
  • ارتقاء کاربران ناشناس - امکان ارتقاء کاربران ناشناس از طریق ورود/ثبت‌نام. برای اطلاعات بیشتر، به بخش ارتقاء کاربران ناشناس مراجعه کنید.

قبل از اینکه شروع کنی

  1. احراز هویت فایربیس را به برنامه وب خود اضافه کنید ، مطمئن شوید که از API با فضای نام نسخه ۹ یا بالاتر استفاده می‌کنید ( نه API ماژولار؛ به نوار کناری بالا مراجعه کنید).

  2. FirebaseUI را از طریق یکی از گزینه‌های زیر اضافه کنید:

    • سی‌دی‌ان

      اسکریپت و فایل 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" />

    • ماژول npm

      FirebaseUI و وابستگی‌های آن را از طریق npm و با استفاده از دستور زیر نصب کنید:

      $ npm install firebaseui --save

      ماژول‌های زیر را در فایل‌های منبع خود require :

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

    • کامپوننت Bower

      FirebaseUI و وابستگی‌های آن را از طریق Bower با استفاده از دستور زیر نصب کنید:

      $ bower install firebaseui --save

      اگر سرور HTTP شما فایل‌های درون bower_components/ را ارائه می‌دهد، فایل‌های مورد نیاز را در HTML خود قرار دهید:

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

مقداردهی اولیه FirebaseUI

پس از وارد کردن SDK، رابط کاربری Auth را مقداردهی اولیه کنید.

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

تنظیم روش‌های ورود به سیستم

قبل از اینکه بتوانید از Firebase برای ورود کاربران استفاده کنید، باید روش‌های ورود به سیستمی را که می‌خواهید پشتیبانی کنید، فعال و پیکربندی کنید.

آدرس ایمیل و رمز عبور

  1. در کنسول Firebase ، به بخش امنیت > احراز هویت بروید.

  2. در تب روش ورود ، گزینه‌ی ارائه‌دهنده‌ی ورود با ایمیل/رمز عبور را فعال کنید.

  3. شناسه ارائه دهنده ایمیل را به لیست signInOptions در FirebaseUI اضافه کنید.

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

  4. اختیاری : EmailAuthProvider را می‌توان طوری پیکربندی کرد که از کاربر بخواهد نام نمایشی (پیش‌فرض true ) را وارد کند.

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

  1. در کنسول Firebase ، به بخش امنیت > احراز هویت بروید.

  2. در تب روش ورود ، گزینه ورود با ایمیل/رمز عبور را فعال کنید. توجه داشته باشید که برای استفاده از ورود با لینک ایمیل، باید ورود با ایمیل/رمز عبور فعال باشد.

  3. در همان بخش، گزینه‌ی «ایمیل لینک (ورود بدون رمز عبور)» را فعال کنید.

  4. روی ذخیره کلیک کنید.

  5. شناسه ارائه دهنده ایمیل را به همراه لینک ایمیل signInMethod به لیست FirebaseUI signInOptions اضافه کنید.

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

  6. هنگام رندر کردن رابط کاربری ورود به سیستم به صورت مشروط (مربوط به برنامه‌های تک صفحه‌ای)، از 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);
}

  7. اختیاری : 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 (گوگل، فیسبوک، توییتر و گیت‌هاب)

  1. در کنسول Firebase ، به بخش امنیت > احراز هویت بروید.

  2. در برگه «روش ورود» ، ورود به سیستم ارائه‌دهنده OAuth مشخص‌شده را فعال کنید. مطمئن شوید که شناسه و رمز کلاینت OAuth مربوطه نیز مشخص شده باشند.

  3. اگر هنوز دامنه برنامه خود را مجاز نکرده‌اید، آن را تأیید کنید:

    1. در کنسول Firebase ، به تب Security > Authentication > Settings بروید.

    2. در بخش دامنه‌های مجاز ، روی افزودن دامنه کلیک کنید و دامنه خود را اضافه کنید.

  4. شناسه ارائه دهنده OAuth را به لیست FirebaseUI signInOptions اضافه کنید. 

    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...
});

  5. اختیاری : برای تعیین محدوده‌های سفارشی یا پارامترهای سفارشی 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. اگر هنوز دامنه برنامه خود را مجاز نکرده‌اید، آن را تأیید کنید:

    1. در کنسول Firebase ، به تب Security > Authentication > Settings بروید.

    2. در بخش دامنه‌های مجاز ، روی افزودن دامنه کلیک کنید و دامنه خود را اضافه کنید.

  4. شناسه ارائه دهنده شماره تلفن را به لیست signInOptions در FirebaseUI اضافه کنید. 

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

  5. اختیاری : PhoneAuthProvider را می‌توان با پارامترهای reCAPTCHA سفارشی پیکربندی کرد، چه reCAPTCHA قابل مشاهده باشد و چه نامرئی (پیش‌فرض روی حالت عادی). برای جزئیات بیشتر به مستندات API 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 در صورت بروز مشکل فوق، تابع callback signInFailure را با کد خطای firebaseui/anonymous-upgrade-merge-conflict فعال می‌کند. شیء خطا همچنین شامل اعتبارنامه دائمی خواهد بود. ورود به سیستم با اعتبارنامه دائمی باید در تابع callback برای تکمیل ورود به سیستم فعال شود. قبل از اینکه ورود به سیستم از طریق 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 استفاده کنید.