FirebaseUI 是建構在 Firebase Authentication SDK 之上的程式庫,可提供用於應用程式的內建 UI 流程。FirebaseUI 具有下列優點:
- 多個供應商:登入電子郵件/密碼、電子郵件連結、電話驗證、Google、Facebook、Twitter 和 GitHub 登入流程。
- 帳戶連結:在不同識別資訊提供者間安全連結使用者帳戶的流程。
- 自訂:根據應用程式需求覆寫 FirebaseUI 的 CSS 樣式。此外,由於 FirebaseUI 是開放原始碼,因此您可以建立專案分支,並完全根據自身需求自訂。
- 輕觸一下即可註冊和自動登入:自動整合一鍵註冊功能,提供快速的跨裝置登入體驗。
- 本地化 UI - 支援超過 40 種語言。
- 升級匿名使用者 - 透過登入/註冊的方式升級匿名使用者。詳情請參閱「升級匿名使用者」一節。
事前準備
將 Firebase 驗證新增至您的網頁應用程式,確保您使用的是 v9 Compat (建議做法) 或舊版 SDK (請參閱上方的側欄)。
透過下列其中一個選項納入 FirebaseUI:
CDN
在 Firebase 控制台的初始化程式碼片段下方,將下列指令碼和 CSS 檔案加入網頁的 <head> 標記中:
<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 模組
使用下列指令,透過 npm 安裝 FirebaseUI 及其依附元件:
$ npm install firebaseui --save
require
來源檔案中的下列模組:var firebase = require('firebase'); var firebaseui = require('firebaseui');
布林值元件
使用下列指令,透過 Bower 安裝 FirebaseUI 及其依附元件:
$ 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 後,請初始化驗證 UI。
// Initialize the FirebaseUI Widget using Firebase.
var ui = new firebaseui.auth.AuthUI(firebase.auth());
設定登入方式
您必須先啟用並設定您想支援的登入方式,才能使用 Firebase 登入使用者。
電子郵件地址和密碼
在 Firebase 主控台中開啟「Authentication」區段,並啟用電子郵件和密碼驗證。
將電子郵件供應商 ID 新增至 FirebaseUI
signInOptions
清單。ui.start('#firebaseui-auth-container', { signInOptions: [ firebase.auth.EmailAuthProvider.PROVIDER_ID ], // Other config options... });
選用:您可以設定
EmailAuthProvider
,要求使用者輸入顯示名稱 (預設為true
)。ui.start('#firebaseui-auth-container', { signInOptions: [ { provider: firebase.auth.EmailAuthProvider.PROVIDER_ID, requireDisplayName: false } ] });
電子郵件連結驗證
在 Firebase 控制台開啟「驗證」專區。在「Sign in method」分頁中,啟用「Email/Password」供應商。請注意,您必須啟用電子郵件/密碼登入功能,才能使用電子郵件連結登入。
在相同區段中,啟用「Email link (無密碼登入)」登入方式,然後按一下「Save」(儲存)。
將電子郵件服務供應商 ID 新增至 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... });
有條件地轉譯登入 UI (與單一頁面應用程式相關) 時,請使用
ui.isPendingRedirect()
偵測網址是否對應於含有電子郵件連結的登入,且需要轉譯 UI 才能完成登入。// 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); }
選用:您可以設定電子郵件連結登入的
EmailAuthProvider
,允許或禁止使用者完成跨裝置登入程序。您可以定義選用的
emailLinkSignIn
回呼,以傳回firebase.auth.ActionCodeSettings
設定,在傳送連結時使用。這樣就能指定處理連結的方式、自訂動態連結、深層連結中的其他狀態等。如未提供,則會使用目前的網址,並觸發純網頁流程。FirebaseUI 網頁的電子郵件連結登入功能與 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)
在 Firebase 主控台中開啟「Authentication」區段,並啟用指定的 OAuth 供應商登入。請確認也指定對應的 OAuth 用戶端 ID 和密鑰。
同樣在「Authentication」(驗證) 部分中,確保將顯示登入頁面的網域也加入授權網域清單。
將 OAuth 供應商 ID 新增至 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... });
選用:如要指定自訂範圍或每個供應商的自訂 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. ] });
電話號碼
在 Firebase 控制台中開啟「驗證」專區,然後啟用電話號碼登入功能。
確保將顯示登入頁面的網域也新增至已授權的網域清單。
將電話號碼供應商 ID 加入 FirebaseUI
signInOptions
清單中。ui.start('#firebaseui-auth-container', { signInOptions: [ firebase.auth.PhoneAuthProvider.PROVIDER_ID ], // Other config options... });
選用:您可以使用自訂 reCAPTCHA 參數設定 PhoneAuthProvider (預設為正常顯示 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 登入流程,請傳遞基礎 Auth
執行個體來初始化 FirebaseUI 執行個體。
// Initialize the FirebaseUI Widget using Firebase.
var ui = new firebaseui.auth.AuthUI(firebase.auth());
定義要轉譯 FirebaseUI 登入小工具的 HTML 元素。
<!-- 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 設定 (支援的供應商和 UI 自訂項目,以及成功回呼等)。
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);
升級匿名使用者
啟用匿名使用者升級
當匿名使用者以永久帳戶登入或註冊時,您一定會想確保使用者可以繼續完成註冊前進行的操作。方法是在設定登入 UI 時,將 autoUpgradeAnonymousUsers
設為 true
(這個選項預設為停用)。
處理匿名使用者升級合併衝突
在某些情況下,使用者一開始以匿名方式登入,嘗試升級至現有的 Firebase 使用者。由於現有使用者無法連結至其他使用者,因此 FirebaseUI 會在發生上述情況時,觸發並傳回錯誤代碼 firebaseui/anonymous-upgrade-merge-conflict
的 signInFailure
回呼。錯誤物件也會包含永久憑證。使用永久憑證登入時,應該會在回呼中觸發以完成登入程序。您必須先儲存匿名使用者的資料並刪除匿名使用者,才能透過 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 問題追蹤工具。