מוסיפים בקלות כניסה לאפליקציית האינטרנט באמצעות FirebaseUI

‫FirebaseUI היא ספרייה שמבוססת על Firebase Authentication SDK ומספקת תהליכי ממשק משתמש מוכנים לשימוש באפליקציה. היתרונות של FirebaseUI:

  • מספר ספקים – תהליכי כניסה לאימות באמצעות אימייל/סיסמה, קישור באימייל, טלפון, כניסה באמצעות Google, פייסבוק, טוויטר ו-GitHub.
  • קישור חשבונות – תהליכים לקישור בטוח של חשבונות משתמשים בין ספקי זהויות.
  • התאמה אישית – אפשר לבטל את סגנונות ה-CSS של FirebaseUI כדי להתאים לדרישות האפליקציה. בנוסף, מכיוון ש-FirebaseUI הוא קוד פתוח, אתם יכולים ליצור עותק של הפרויקט ולהתאים אותו בדיוק לצרכים שלכם.
  • הרשמה בלחיצה אחת וכניסה אוטומטית – שילוב אוטומטי עם הרשמה בלחיצה אחת לכניסה מהירה לחשבון במכשירים שונים.
  • ממשק משתמש מותאם לשפה – התאמה לשוק הבינלאומי ביותר מ-40 שפות.
  • שדרוג משתמשים אנונימיים – אפשרות לשדרג משתמשים אנונימיים באמצעות כניסה או הרשמה. מידע נוסף זמין בקטע בנושא שדרוג משתמשים אנונימיים.

לפני שמתחילים

  1. מוסיפים אימות ב-Firebase לאפליקציית האינטרנט, ומוודאים שאתם משתמשים ב-API עם מרחב שמות בגרסה 9 ואילך (לא ב-API מודולרי; ראו את סרגל הצד שלמעלה).

  2. אפשר לכלול את FirebaseUI באחת מהדרכים הבאות:

    • CDN

      מוסיפים את הסקריפט הבא ואת קובץ ה-CSS לתג <head> של הדף, מתחת לקטע הקוד לאתחול מFirebase Console:

      <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 Module

      מתקינים את 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, מאתחלים את ממשק המשתמש של האימות.

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

הגדרת שיטות כניסה

כדי להשתמש ב-Firebase כדי לאפשר למשתמשים להיכנס לחשבון, צריך להפעיל ולהגדיר את שיטות הכניסה שרוצים לתמוך בהן.

כתובת אימייל וסיסמה

  1. במסוף Firebase, עוברים אל Security (אבטחה) >‏ Authentication (אימות).

  2. בכרטיסייה שיטת כניסה, מפעילים את ספק הכניסה אימייל/סיסמה.

  3. מוסיפים את מזהה ספק האימייל לרשימה של FirebaseUI signInOptions.

    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, עוברים אל Security (אבטחה) >‏ Authentication (אימות).

  2. בכרטיסייה שיטת כניסה, מפעילים את ספק הכניסה אימייל/סיסמה. שימו לב: כדי להשתמש בכניסה באמצעות קישור באימייל, צריך להפעיל את הכניסה באמצעות אימייל או סיסמה.

  3. באותו קטע, מפעילים את ספק הכניסה Email link (passwordless sign-in) (קישור באימייל – כניסה ללא סיסמה).

  4. לוחצים על שמירה.

  5. מוסיפים את מזהה ספק האימייל לרשימה של 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...
});

  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 לכניסה באמצעות קישור באימייל כך שיאפשר או יחסום את המשתמש להשלים כניסה בין מכשירים.

    אפשר להגדיר קריאה חוזרת (callback) אופציונלית 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, עוברים אל Security (אבטחה) >‏ Authentication (אימות).

  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, עוברים אל Security (אבטחה) >‏ Authentication (אימות).

  2. בכרטיסייה שיטת כניסה, מפעילים את ספק הכניסה טלפון.

  3. אם עדיין לא עשיתם זאת, צריך לתת הרשאה לדומיין של האפליקציה:

    1. במסוף Firebase, עוברים אל Security (אבטחה) > Authentication (אימות) > הכרטיסייה Settings (הגדרות).

    2. בקטע דומיינים מורשים, לוחצים על הוספת דומיין ומוסיפים את הדומיין.

  4. מוסיפים את מזהה ספק מספר הטלפון לרשימה של FirebaseUI signInOptions.

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

  5. אופציונלי: אפשר להגדיר את PhoneAuthProvider עם פרמטרים מותאמים אישית של reCAPTCHA, בין אם reCAPTCHA גלוי או בלתי נראה (ברירת המחדל היא רגיל). פרטים נוספים זמינים במסמכי העזרה של reCAPTCHA API.

    אפשר גם להגדיר את המדינה שתוצג כברירת מחדל בשדה להזנת מספר הטלפון. רשימת קידומות המדינות הנתמכות אם לא מציינים ערך, ברירת המחדל של קלט מספר הטלפון היא ארצות הברית (+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 (ספקים נתמכים והתאמות אישיות של ממשק המשתמש, וגם קריאות חוזרות (callback) להצלחה וכו').

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:

// 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 כשהתרחיש שלמעלה יקרה. אובייקט השגיאה יכיל גם את פרטי הכניסה הקבועים. הכניסה באמצעות פרטי הכניסה הקבועים צריכה להיות מופעלת בקריאה החוזרת כדי להשלים את הכניסה. כדי להשלים את הכניסה דרך 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 ואתם רוצים לדווח עליה, אתם יכולים להשתמש בכלי Issue Tracker ב-GitHub.