创建自定义电子邮件操作处理程序

某些用户管理操作(例如,更新用户的电子邮件地址和重置用户的密码)会导致向用户发送电子邮件。这些电子邮件会包含一些链接,收件人可以打开这些链接来完成或取消用户管理操作。默认情况下,用户管理电子邮件会链接到默认操作处理程序,该处理程序是在您的项目的 Firebase 托管网域中的某个网址处托管的一个网页。

您也可以创建并托管一个自定义电子邮件操作处理程序,以进行自定义处理以及将该电子邮件操作处理程序与您的网站集成到一起。

下面的用户管理操作要求用户使用电子邮件操作处理程序来完成操作:

  • 重置密码
  • 撤消电子邮件地址更改 - 当用户更改其帐号的主电子邮件地址时,Firebase 会向其旧电子邮件地址发送一封邮件,用户可在其中撤消该电子邮件地址更改。
  • 确认电子邮件地址

要自定义您的 Firebase 项目的电子邮件操作处理程序,您必须创建并托管一个网页,该网页使用 Firebase JavaScript SDK 来验证请求的有效性并完成请求。然后,您必须自定义您的 Firebase 项目的电子邮件模板以关联到您的自定义操作处理程序。

创建电子邮件操作处理程序页面

  1. Firebase 在生成用户管理电子邮件时,会将多个查询参数添加到您的操作处理程序网址。例如:

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

    这些参数指明了用户正在完成的用户管理任务。您的电子邮件操作处理程序页面必须处理以下查询参数:

    参数
    mode

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

    • resetPassword
    • recoverEmail
    • verifyEmail
    oobCode 一个一次性代码,用于识别和验证请求
    apiKey 您的 Firebase 项目的 API 密钥(提供该密钥是为了方便您进行操作)
    continueUrl 这是一个可选网址,提供了一种通过网址将状态传回应用的方法。这与重设密码和电子邮件验证模式相关。当发送重置密码电子邮件或验证电子邮件时,需要为 ActionCodeSettings 对象指定接续网址,才能达到相应目的。这使得用户可以在执行电子邮件操作之后从他们原先所在的位置继续。
    lang

    这是表示用户语言区域的可选 BCP47 语言标记(例如,fr)。您可以使用此值为用户提供本地化的电子邮件操作处理程序页面。

    您可以通过 Firebase 控制台设置本地化语言,也可以在触发电子邮件操作之前通过调用相应的客户端 API 动态设置本地化语言。例如,使用以下 JavaScript:firebase.auth().languageCode = 'fr';

    要获得一致的用户体验,请确保电子邮件操作处理程序的本地化语言与电子邮件模板的本地化语言相同。

    以下示例显示了在基于浏览器的处理程序中如何处理查询参数。(您也可以使用相似的逻辑,以 Node.js 应用的形式实现该处理程序。)

    <script src="https://www.gstatic.com/firebasejs/5.3.0/firebase.js"></script>
    <script>
    document.addEventListener('DOMContentLoaded', function() {
      // 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 API key from the query parameter.
      var apiKey = getParameterByName('apiKey');
      // (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': apiKey  // This key could also be copied 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);
    </script>
    
  2. 处理密码重置请求,方法如下:首先,使用 verifyPasswordResetCode 验证操作代码;然后,从用户处获取一个新密码并将其传递给 confirmPasswordReset。例如:

    function handleResetPassword(auth, actionCode, continueUrl, lang) {
      // Localize the UI to the selected language as determined by the lang
      // parameter.
      var accountEmail;
      // Verify the password reset code is valid.
      auth.verifyPasswordResetCode(actionCode).then(function(email) {
        var accountEmail = email;
    
        // TODO: Show the reset screen with the user's email and ask the user for
        // the new password.
    
        // Save the new password.
        auth.confirmPasswordReset(actionCode, newPassword).then(function(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(function(error) {
          // Error occurred during confirmation. The code might have expired or the
          // password is too weak.
        });
      }).catch(function(error) {
        // Invalid or expired action code. Ask user to try to reset the password
        // again.
      });
    }
    
  3. 处理电子邮件地址更改撤消,方法如下:首先,使用 checkActionCode 验证操作代码;然后,使用 applyActionCode 恢复用户的电子邮件地址。例如:

    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(function(info) {
        // Get the restored email address.
        restoredEmail = info['data']['email'];
    
        // Revert to the old email.
        return auth.applyActionCode(actionCode);
      }).then(function() {
        // 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(function() {
          // Password reset confirmation sent. Ask user to check their email.
        }).catch(function(error) {
          // Error encountered while sending password reset code.
        });
      }).catch(function(error) {
        // Invalid code.
      });
    }
    
  4. 通过调用 applyActionCode 处理电子邮件地址验证。例如:

    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(function(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(function(error) {
        // Code is invalid or expired. Ask the user to verify their email address
        // again.
      });
    }
    
  5. 将页面托管于某处,比如使用 Firebase 托管。

接下来,您必须将您的 Firebase 项目配置为关联到其用户管理电子邮件中的您的自定义电子邮件操作处理程序。

要将您的 Firebase 项目配置为使用您的自定义电子邮件操作处理程序,请按以下步骤操作:

  1. Firebase 控制台中打开您的项目。
  2. Authentication(身份验证)部分中打开电子邮件模板页面。
  3. 在任一电子邮件类型条目中,点击铅笔图标以编辑电子邮件模板。
  4. 点击自定义操作网址,然后指定您的自定义电子邮件操作处理程序的网址。

在您保存该网址之后,您的所有 Firebase 项目的电子邮件模板将都可以使用该网址。

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面