FirebaseUI là một thư viện được xây dựng dựa trên SDK Xác thực Firebase, cung cấp các luồng giao diện người dùng thả vào để sử dụng trong ứng dụng của bạn. FirebaseUI mang lại những lợi ích sau:
- Nhiều nhà cung cấp – luồng đăng nhập cho email/mật khẩu, đường liên kết email, xác thực qua điện thoại, đăng nhập bằng Google, Facebook, Twitter và GitHub.
- Liên kết tài khoản – luồng để liên kết an toàn các tài khoản người dùng trên nhiều nhà cung cấp danh tính.
- Tuỳ chỉnh – ghi đè các kiểu CSS của FirebaseUI để phù hợp với yêu cầu của ứng dụng. Ngoài ra, vì FirebaseUI là nguồn mở, nên bạn có thể phát triển nhánh dự án và tuỳ chỉnh chính xác theo nhu cầu của mình.
- Đăng ký bằng một lần chạm và tự động đăng nhập – tự động tích hợp với tính năng Đăng ký bằng một lần chạm để đăng nhập nhanh trên nhiều thiết bị.
- Giao diện người dùng được bản địa hoá – quốc tế hoá cho hơn 40 ngôn ngữ.
- Nâng cấp người dùng ẩn danh – khả năng nâng cấp người dùng ẩn danh thông qua quy trình đăng nhập/đăng ký. Để biết thêm thông tin, hãy xem phần Nâng cấp người dùng ẩn danh section.
Trước khi bắt đầu
Thêm tính năng Xác thực Firebase vào ứng dụng web của bạn, đảm bảo rằng bạn đang sử dụng API có không gian tên v9 trở lên (không phải API mô-đun; xem thanh bên ở trên).
Thêm FirebaseUI thông qua một trong các lựa chọn sau:
CDN
Thêm tập lệnh và tệp CSS sau vào thẻ <head> của trang, bên dưới đoạn mã khởi chạy từ Firebase bảng điều khiển:
<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" />Mô-đun npm
Cài đặt FirebaseUI và các phần phụ thuộc của nó thông qua npm bằng lệnh sau:
$ npm install firebaseui --saverequirecác mô-đun sau trong tệp nguồn của bạn:var firebase = require('firebase'); var firebaseui = require('firebaseui');
Thành phần Bower
Cài đặt FirebaseUI và các phần phụ thuộc của nó thông qua Bower bằng lệnh sau:
$ bower install firebaseui --save
Thêm các tệp bắt buộc vào HTML của bạn, nếu Máy chủ HTTP của bạn phân phát các tệp trong
bower_components/:<script src="bower_components/firebaseui/dist/firebaseui.js"></script> <link type="text/css" rel="stylesheet" href="bower_components/firebaseui/dist/firebaseui.css" />
Khởi chạy FirebaseUI
Sau khi nhập SDK, hãy khởi chạy Giao diện người dùng xác thực.
// Initialize the FirebaseUI Widget using Firebase.
var ui = new firebaseui.auth.AuthUI(firebase.auth());
Thiết lập phương thức đăng nhập
Trước khi có thể sử dụng Firebase để đăng nhập người dùng, bạn phải bật và định cấu hình các phương thức đăng nhập mà bạn muốn hỗ trợ.
Địa chỉ email và mật khẩu
Trong bảng điều khiển Firebase, hãy chuyển đến Security > Authentication.
Trong thẻ Sign-in method (Phương thức đăng nhập), hãy bật nhà cung cấp dịch vụ đăng nhập Email/Password (Email/Mật khẩu).
Thêm mã nhà cung cấp email vào danh sách
signInOptionscủa FirebaseUI.ui.start('#firebaseui-auth-container', { signInOptions: [ firebase.auth.EmailAuthProvider.PROVIDER_ID ], // Other config options... });
Không bắt buộc: Bạn có thể định cấu hình
EmailAuthProviderđể yêu cầu người dùng nhập tên hiển thị (mặc định làtrue).ui.start('#firebaseui-auth-container', { signInOptions: [ { provider: firebase.auth.EmailAuthProvider.PROVIDER_ID, requireDisplayName: false } ] });
Xác thực bằng đường liên kết email
Trong bảng điều khiển Firebase, hãy chuyển đến Security > Authentication.
Trong thẻ Sign-in method (Phương thức đăng nhập), hãy bật nhà cung cấp dịch vụ đăng nhập Email/Password (Email/Mật khẩu). Xin lưu ý rằng bạn phải bật tính năng đăng nhập bằng email/mật khẩu để sử dụng tính năng đăng nhập bằng đường liên kết email.
Trong cùng một phần, hãy bật nhà cung cấp dịch vụ đăng nhập Email link (passwordless sign-in) (Đường liên kết email (đăng nhập không cần mật khẩu)).
Nhấp vào Lưu.
Thêm mã nhà cung cấp email vào danh sách
signInOptionscủa FirebaseUI cùng vớisignInMethodđường liên kết email.ui.start('#firebaseui-auth-container', { signInOptions: [ { provider: firebase.auth.EmailAuthProvider.PROVIDER_ID, signInMethod: firebase.auth.EmailAuthProvider.EMAIL_LINK_SIGN_IN_METHOD } ], // Other config options... });
Khi kết xuất giao diện người dùng đăng nhập có điều kiện (phù hợp với các ứng dụng một trang), hãy sử dụng
ui.isPendingRedirect()để phát hiện xem URL có tương ứng với quy trình đăng nhập bằng đường liên kết email hay không và giao diện người dùng cần được kết xuất để hoàn tất quy trình đăng nhập.// 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); }
Không bắt buộc: Bạn có thể định cấu hình
EmailAuthProvidercho quy trình đăng nhập bằng đường liên kết email để cho phép hoặc chặn người dùng hoàn tất quy trình đăng nhập trên nhiều thiết bị.Bạn có thể xác định lệnh gọi lại
emailLinkSignInkhông bắt buộc để trả về cấu hìnhfirebase.auth.ActionCodeSettingscần sử dụng khi gửi đường liên kết. Điều này cho phép bạn chỉ định cách xử lý đường liên kết, đường liên kết động tuỳ chỉnh, trạng thái bổ sung trong đường liên kết sâu, v.v. Khi không được cung cấp, URL hiện tại sẽ được sử dụng và một luồng chỉ dành cho web sẽ được kích hoạt.Quy trình đăng nhập bằng đường liên kết email trong FirebaseUI-web tương thích với FirebaseUI-Android và FirebaseUI-iOS trong đó một người dùng bắt đầu luồng từ FirebaseUI-Android có thể mở đường liên kết và hoàn tất quy trình đăng nhập bằng FirebaseUI-web. Điều này cũng đúng đối với luồng ngược lại.
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' } }; } } ] });
Nhà cung cấp OAuth (Google, Facebook, Twitter và GitHub)
Trong bảng điều khiển Firebase, hãy chuyển đến Security > Authentication.
Trong thẻ Sign-in method (Phương thức đăng nhập), hãy bật tính năng đăng nhập bằng nhà cung cấp OAuth đã chỉ định. Đảm bảo bạn cũng đã chỉ định mã và khoá bí mật của ứng dụng OAuth tương ứng.
Nếu bạn chưa làm, hãy cho phép miền của ứng dụng:
Trong bảng điều khiển Firebase, hãy chuyển đến thẻ Security > Authentication > Settings.
Trong phần Authorized domains (Miền được phép), hãy nhấp vào Add domain (Thêm miền) rồi thêm miền của bạn.
Thêm mã nhà cung cấp OAuth vào danh sách
signInOptionscủa 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... });
Không bắt buộc: Để chỉ định các phạm vi tuỳ chỉnh hoặc tham số OAuth tuỳ chỉnh cho mỗi nhà cung cấp, bạn có thể truyền một đối tượng thay vì chỉ truyền giá trị nhà cung cấp:
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. ] });
Số điện thoại
Trong bảng điều khiển Firebase, hãy chuyển đến Security > Authentication.
Trong thẻ Sign-in method (Phương thức đăng nhập), hãy bật nhà cung cấp dịch vụ đăng nhập Phone (Điện thoại).
Nếu bạn chưa làm, hãy cho phép miền của ứng dụng:
Trong bảng điều khiển Firebase, hãy chuyển đến thẻ Security (Bảo mật) > Authentication (Xác thực) > Settings (Cài đặt).
Trong phần Authorized domains (Miền được phép), hãy nhấp vào Add domain (Thêm miền) rồi thêm miền của bạn.
Thêm mã nhà cung cấp số điện thoại vào danh sách
signInOptionscủa FirebaseUI.ui.start('#firebaseui-auth-container', { signInOptions: [ firebase.auth.PhoneAuthProvider.PROVIDER_ID ], // Other config options... });
Không bắt buộc: Bạn có thể định cấu hình PhoneAuthProvider bằng các tham số reCAPTCHA tuỳ chỉnh, cho dù reCAPTCHA hiển thị hay không hiển thị (mặc định là bình thường). Hãy tham khảo tài liệu về reCAPTCHA API để biết thêm chi tiết.
Bạn cũng có thể đặt quốc gia mặc định để chọn trong phần nhập số điện thoại. Hãy tham khảo danh sách mã quốc gia được hỗ trợ để xem danh sách đầy đủ các mã. Nếu bạn không chỉ định, phần nhập số điện thoại sẽ mặc định là Hoa Kỳ (+1).
Các lựa chọn sau hiện được hỗ trợ.
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' } ] });
Đăng nhập
Để bắt đầu luồng đăng nhập FirebaseUI, hãy khởi chạy thực thể FirebaseUI bằng cách truyền thực thể Auth cơ bản.
// Initialize the FirebaseUI Widget using Firebase.
var ui = new firebaseui.auth.AuthUI(firebase.auth());
Xác định phần tử HTML nơi tiện ích đăng nhập FirebaseUI sẽ được kết xuất.
<!-- 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>
Chỉ định cấu hình FirebaseUI (các nhà cung cấp được hỗ trợ và các tuỳ chỉnh giao diện người dùng cũng như lệnh gọi lại thành công, v.v.).
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>'
};
Cuối cùng, hãy kết xuất giao diện Xác thực FirebaseUI:
// The start method will wait until the DOM is loaded.
ui.start('#firebaseui-auth-container', uiConfig);
Nâng cấp người dùng ẩn danh
Bật tính năng nâng cấp người dùng ẩn danh
Khi người dùng ẩn danh đăng nhập hoặc đăng ký bằng tài khoản vĩnh viễn, bạn cần đảm bảo rằng người dùng có thể tiếp tục những gì họ đang làm trước khi đăng ký.
Để làm như vậy, bạn chỉ cần đặt autoUpgradeAnonymousUsers thành true khi định cấu hình giao diện người dùng đăng nhập (tuỳ chọn này bị tắt theo mặc định).
Xử lý các xung đột hợp nhất khi nâng cấp người dùng ẩn danh
Có những trường hợp người dùng ban đầu đăng nhập ẩn danh, cố gắng nâng cấp lên người dùng Firebase hiện có. Vì người dùng hiện có không thể liên kết với người dùng hiện có khác, nên FirebaseUI sẽ kích hoạt lệnh gọi lại signInFailure với mã lỗi firebaseui/anonymous-upgrade-merge-conflict khi trường hợp trên xảy ra.
Đối tượng lỗi cũng sẽ chứa thông tin xác thực vĩnh viễn. Bạn nên kích hoạt quy trình đăng nhập bằng thông tin xác thực vĩnh viễn trong lệnh gọi lại để hoàn tất quy trình đăng nhập.
Trước khi có thể hoàn tất quy trình đăng nhập thông qua auth.signInWithCredential(error.credential), bạn phải lưu dữ liệu của người dùng ẩn danh và xoá người dùng ẩn danh. Sau đó, sau khi hoàn tất quy trình đăng nhập, hãy sao chép dữ liệu trở lại người dùng không ẩn danh. Ví dụ dưới đây minh hoạ cách hoạt động của luồng này.
// 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);
}
}
});