建立自訂電子郵件操作處理程序

某些使用者管理操作(例如更新使用者的電子郵件地址和重設使用者的密碼)會導致向使用者發送電子郵件。這些電子郵件包含收件者可以開啟以完成或取消使用者管理操作的連結。預設情況下,使用者管理電子郵件連結到預設操作處理程序,該處理程序是託管在專案的 Firebase 託管網域中的 URL 上的網頁。

您可以改為建立並託管自訂電子郵件操作處理程序來執行自訂處理並將電子郵件操作處理程序與您的網站整合。

以下使用者管理操作要求使用者使用電子郵件操作處理程序完成操作:

  • 重設密碼
  • 撤銷電子郵件地址變更 - 當使用者變更帳戶的主電子郵件地址時,Firebase 會向他們的舊地址發送電子郵件,允許他們撤銷更改
  • 驗證電子郵件地址

要自訂 Firebase 專案的電子郵件操作處理程序,您必須建立並託管一個網頁,該網頁使用 Firebase JavaScript SDK 來驗證請求的有效性並完成請求。然後,您必須自訂 Firebase 專案的電子郵件範本以連結到您的自訂作業處理程序。

建立電子郵件操作處理程序頁面

  1. Firebase 在產生使用者管理電子郵件時會為您的操作處理程序 URL 新增多個查詢參數。例如:

    https://example.com/usermgmt?mode=resetPassword&oobCode=ABC123&apiKey=AIzaSy...&lang=fr

    這些參數指定使用者正在完成的使用者管理任務。您的電子郵件操作處理程序頁面必須處理下列查詢參數:

    參數
    模式

    要完成的使用者管理操作。可以是以下值之一:

    • resetPassword
    • recoverEmail
    • verifyEmail
    出庫程式碼一次性代碼,用於識別和驗證請求
    API金鑰您的 Firebase 專案的 API 金鑰,為方便起見而提供
    繼續網址這是一個可選的 URL,它提供了一種透過 URL 將狀態傳遞回應用程式的方法。這與密碼重設和電子郵件驗證模式有關。發送密碼重設電子郵件或驗證電子郵件時,需要使用繼續 URL 指定ActionCodeSettings物件才能使其可用。這使得用戶可以在執行電子郵件操作後從上次中斷的地方繼續操作。

    這是表示使用者區域設定的可選BCP47語言標記(例如fr )。您可以使用此值向使用者提供本地化的電子郵件操作處理程序頁面。

    本地化可以透過 Firebase 控制台進行設置,也可以在觸發電子郵件操作之前透過呼叫相應的客戶端 API 來動態設置。例如,使用 JavaScript: firebase.auth().languageCode = 'fr';

    為了獲得一致的使用者體驗,請確保電子郵件操作處理程序在地化與電子郵件範本相符。

    以下範例顯示如何在基於瀏覽器的處理程序中處理查詢參數。 (您也可以使用類似的邏輯將處理程序實作為 Node.js 應用程式。)

    Web modular API

    import { initializeApp } from "firebase/app";
    import { getAuth } from "firebase/auth";
    
    document.addEventListener('DOMContentLoaded', () => {
      // TODO: Implement getParameterByName()
    
      // Get the action to complete.
      const mode = getParameterByName('mode');
      // Get the one-time code from the query parameter.
      const actionCode = getParameterByName('oobCode');
      // (Optional) Get the continue URL from the query parameter if available.
      const continueUrl = getParameterByName('continueUrl');
      // (Optional) Get the language code if available.
      const lang = getParameterByName('lang') || 'en';
    
      // Configure the Firebase SDK.
      // This is the minimum configuration required for the API to be used.
      const config = {
        'apiKey': "YOUR_API_KEY" // Copy this key from the web initialization
                                 // snippet found in the Firebase console.
      };
      const app = initializeApp(config);
      const auth = getAuth(app);
    
      // Handle the user management action.
      switch (mode) {
        case 'resetPassword':
          // Display reset password handler and UI.
          handleResetPassword(auth, actionCode, continueUrl, lang);
          break;
        case 'recoverEmail':
          // Display email recovery handler and UI.
          handleRecoverEmail(auth, actionCode, lang);
          break;
        case 'verifyEmail':
          // Display email verification handler and UI.
          handleVerifyEmail(auth, actionCode, continueUrl, lang);
          break;
        default:
          // Error: invalid mode.
      }
    }, false);

    Web namespaced API

    document.addEventListener('DOMContentLoaded', () => {
      // TODO: Implement getParameterByName()
    
      // Get the action to complete.
      var mode = getParameterByName('mode');
      // Get the one-time code from the query parameter.
      var actionCode = getParameterByName('oobCode');
      // (Optional) Get the continue URL from the query parameter if available.
      var continueUrl = getParameterByName('continueUrl');
      // (Optional) Get the language code if available.
      var lang = getParameterByName('lang') || 'en';
    
      // Configure the Firebase SDK.
      // This is the minimum configuration required for the API to be used.
      var config = {
        'apiKey': "YOU_API_KEY" // Copy this key from the web initialization
                                // snippet found in the Firebase console.
      };
      var app = firebase.initializeApp(config);
      var auth = app.auth();
    
      // Handle the user management action.
      switch (mode) {
        case 'resetPassword':
          // Display reset password handler and UI.
          handleResetPassword(auth, actionCode, continueUrl, lang);
          break;
        case 'recoverEmail':
          // Display email recovery handler and UI.
          handleRecoverEmail(auth, actionCode, lang);
          break;
        case 'verifyEmail':
          // Display email verification handler and UI.
          handleVerifyEmail(auth, actionCode, continueUrl, lang);
          break;
        default:
          // Error: invalid mode.
      }
    }, false);
  2. 透過先使用verifyPasswordResetCode驗證操作代碼來處理密碼重設請求;然後從用戶那裡獲取新密碼並將其傳遞給confirmPasswordReset 。例如:

    Web modular API

    import { verifyPasswordResetCode, confirmPasswordReset } from "firebase/auth";
    
    function handleResetPassword(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
    
      // Verify the password reset code is valid.
      verifyPasswordResetCode(auth, actionCode).then((email) => {
        const accountEmail = email;
    
        // TODO: Show the reset screen with the user's email and ask the user for
        // the new password.
        const newPassword = "...";
    
        // Save the new password.
        confirmPasswordReset(auth, actionCode, newPassword).then((resp) => {
          // Password reset has been confirmed and new password updated.
    
          // TODO: Display a link back to the app, or sign-in the user directly
          // if the page belongs to the same domain as the app:
          // auth.signInWithEmailAndPassword(accountEmail, newPassword);
    
          // TODO: If a continue URL is available, display a button which on
          // click redirects the user back to the app via continueUrl with
          // additional state determined from that URL's parameters.
        }).catch((error) => {
          // Error occurred during confirmation. The code might have expired or the
          // password is too weak.
        });
      }).catch((error) => {
        // Invalid or expired action code. Ask user to try to reset the password
        // again.
      });
    }

    Web namespaced API

    function handleResetPassword(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
    
      // Verify the password reset code is valid.
      auth.verifyPasswordResetCode(actionCode).then((email) => {
        var accountEmail = email;
    
        // TODO: Show the reset screen with the user's email and ask the user for
        // the new password.
        var newPassword = "...";
    
        // Save the new password.
        auth.confirmPasswordReset(actionCode, newPassword).then((resp) => {
          // Password reset has been confirmed and new password updated.
    
          // TODO: Display a link back to the app, or sign-in the user directly
          // if the page belongs to the same domain as the app:
          // auth.signInWithEmailAndPassword(accountEmail, newPassword);
    
          // TODO: If a continue URL is available, display a button which on
          // click redirects the user back to the app via continueUrl with
          // additional state determined from that URL's parameters.
        }).catch((error) => {
          // Error occurred during confirmation. The code might have expired or the
          // password is too weak.
        });
      }).catch((error) => {
        // Invalid or expired action code. Ask user to try to reset the password
        // again.
      });
    }
  3. 首先使用checkActionCode驗證操作代碼來處理電子郵件地址變更撤銷;然後使用applyActionCode恢復使用者的電子郵件地址。例如:

    Web modular API

    import { checkActionCode, applyActionCode, sendPasswordResetEmail } from "firebase/auth";
    
    function handleRecoverEmail(auth, actionCode, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      let restoredEmail = null;
      // Confirm the action code is valid.
      checkActionCode(auth, actionCode).then((info) => {
        // Get the restored email address.
        restoredEmail = info['data']['email'];
    
        // Revert to the old email.
        return applyActionCode(auth, actionCode);
      }).then(() => {
        // Account email reverted to restoredEmail
    
        // TODO: Display a confirmation message to the user.
    
        // You might also want to give the user the option to reset their password
        // in case the account was compromised:
        sendPasswordResetEmail(auth, restoredEmail).then(() => {
          // Password reset confirmation sent. Ask user to check their email.
        }).catch((error) => {
          // Error encountered while sending password reset code.
        });
      }).catch((error) => {
        // Invalid code.
      });
    }

    Web namespaced API

    function handleRecoverEmail(auth, actionCode, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      var restoredEmail = null;
      // Confirm the action code is valid.
      auth.checkActionCode(actionCode).then((info) => {
        // Get the restored email address.
        restoredEmail = info['data']['email'];
    
        // Revert to the old email.
        return auth.applyActionCode(actionCode);
      }).then(() => {
        // Account email reverted to restoredEmail
    
        // TODO: Display a confirmation message to the user.
    
        // You might also want to give the user the option to reset their password
        // in case the account was compromised:
        auth.sendPasswordResetEmail(restoredEmail).then(() => {
          // Password reset confirmation sent. Ask user to check their email.
        }).catch((error) => {
          // Error encountered while sending password reset code.
        });
      }).catch((error) => {
        // Invalid code.
      });
    }
  4. 透過呼叫applyActionCode處理電子郵件地址驗證。例如:

    Web modular API

    function handleVerifyEmail(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      // Try to apply the email verification code.
      applyActionCode(auth, actionCode).then((resp) => {
        // Email address has been verified.
    
        // TODO: Display a confirmation message to the user.
        // You could also provide the user with a link back to the app.
    
        // TODO: If a continue URL is available, display a button which on
        // click redirects the user back to the app via continueUrl with
        // additional state determined from that URL's parameters.
      }).catch((error) => {
        // Code is invalid or expired. Ask the user to verify their email address
        // again.
      });
    }

    Web namespaced API

    function handleVerifyEmail(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      // Try to apply the email verification code.
      auth.applyActionCode(actionCode).then((resp) => {
        // Email address has been verified.
    
        // TODO: Display a confirmation message to the user.
        // You could also provide the user with a link back to the app.
    
        // TODO: If a continue URL is available, display a button which on
        // click redirects the user back to the app via continueUrl with
        // additional state determined from that URL's parameters.
      }).catch((error) => {
        // Code is invalid or expired. Ask the user to verify their email address
        // again.
      });
    }
  5. 將頁面託管在某處,例如使用Firebase Hosting

接下來,您必須將 Firebase 專案配置為連結到其使用者管理電子郵件中的自訂電子郵件操作處理程序。

若要將 Firebase 專案配置為使用自訂電子郵件操作處理程序,請執行下列操作:

  1. Firebase 控制台中開啟您的專案。
  2. 前往「身份驗證」部分中的「電子郵件範本」頁面。
  3. 在任何電子郵件類型條目中,按一下鉛筆圖示以編輯電子郵件範本。
  4. 按一下自訂操作 URL ,然後指定自訂電子郵件操作處理程序的 URL。

儲存 URL 後,您的所有 Firebase 專案的電子郵件範本都會使用該 URL。