Criar gerenciadores de ações de e-mail personalizados

Algumas ações de gerenciamento de usuários, como atualizar o endereço de e-mail e redefinir a senha, resultam no envio de e-mails para ele. Esses e-mails contêm links que os destinatários podem abrir para concluir ou cancelar a ação de gerenciamento de usuários. Por padrão, os e-mails de gerenciamento de usuários são vinculados a um gerenciador de ação padrão, que é uma página da Web hospedada em um URL no domínio do Firebase Hosting do seu projeto.

Em vez disso, você pode criar e hospedar um gerenciador personalizado de ações de e-mail para personalizar o processamento e integrar o gerenciador ao seu site.

As seguintes ações de gerenciamento de usuários exigem que o usuário utilize um gerenciador de ações de e-mail:

Como redefinir senhas
Revogação de alterações de endereço de e-mail: quando os usuários mudam o endereço de e-mail primário da conta, uma mensagem é enviada pelo Firebase ao antigo endereço para que os usuários possam desfazer a alteração.
Verificação de endereços de e-mail

Para personalizar o gerenciador de ações de e-mail do seu projeto do Firebase, crie e hospede uma página da Web que use o SDK do Firebase para JavaScript para verificar a validade da solicitação e concluí-la. Em seguida, personalize os modelos de e-mail do seu projeto do Firebase e vincule-os ao seu gerenciador de ações personalizado.

Criar a página do gerenciador de ações de e-mail

Vários parâmetros de consulta são adicionados ao URL do gerenciador de ações quando e-mails de gerenciamento de usuários são gerados pelo Firebase. Por exemplo:

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

Esses parâmetros especificam a tarefa de gerenciamento de usuários que está sendo realizada. Sua página do gerenciador de ações de e-mail precisa resolver os seguintes parâmetros de consulta:

Parâmetros
modo	A ação de gerenciamento de usuários a ser concluída. Pode ser um dos seguintes valores: `resetPassword` `recoverEmail` `verifyEmail`
oobCode	Um código único utilizado para identificar e verificar uma solicitação.
apiKey	A chave de API do seu projeto do Firebase, fornecida para fins de praticidade.
continueUrl	Esse é um URL opcional que fornece uma maneira de transmitir o estado de volta ao app por um URL. Isso é relevante para os modos de redefinição de senha e verificação de e-mail. Ao enviar um e-mail de redefinição de senha ou um e-mail de verificação, um objeto `ActionCodeSettings` precisa ser especificado com um URL de confirmação para que ele esteja disponível. Isso permite que um usuário continue de onde parou depois de uma ação de e-mail.
lang	Esta é a tag de idioma BCP47 opcional que representa a localidade do usuário (por exemplo, `fr`). Use esse valor para fornecer páginas localizadas do gerenciador de ações de e-mail para seus usuários. A localização pode ser definida por meio do Console do Firebase ou dinamicamente. Para isso, chame a API do cliente correspondente antes de acionar a ação de e-mail. Por exemplo, usando JavaScript: `firebase.auth().languageCode = 'fr';`. Para uma experiência de usuário consistente, verifique se a localização do gerenciador de ações de e-mail corresponde àquela dos modelos de e-mail.

O exemplo a seguir mostra como processar os parâmetros de consulta em um gerenciador baseado em navegador. Você também pode implementar o gerenciador como um aplicativo Node.js usando uma lógica semelhante.

Web

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);auth_handle_mgmt_query_params.js

Web

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);custom-email-handler.js

Gerencie as solicitações de redefinição de senha verificando primeiro o código de ação com verifyPasswordResetCode. Em seguida, receba uma nova senha do usuário e transmita-a para confirmPasswordReset. Por exemplo:

Web

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.
  });
}auth_handle_reset_password.js

Web

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.
  });
}custom-email-handler.js

Gerencie as revogações de alteração de endereço de e-mail verificando primeiro o código de ação com checkActionCode. Em seguida, restaure o endereço de e-mail do usuário com applyActionCode. Por exemplo:

Web

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.
  });
}auth_handle_recover_email.js

Web

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.
  });
}custom-email-handler.js

Para gerenciar a verificação de endereço de e-mail, chame applyActionCode. Por exemplo:

Web

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.
  });
}auth_handle_verify_email.js

Web

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.
  });
}custom-email-handler.js

Hospede a página em algum lugar, por exemplo, usando o Firebase Hosting.

Em seguida, vincule seu gerenciador personalizado de ações de e-mail ao seu projeto do Firebase nos e-mails de gerenciamento de usuários.

Vincular o gerenciador personalizado nos seus modelos de e-mail

Para configurar seu projeto do Firebase de forma que ele use um gerenciador personalizado de ações de e-mail:

Abra seu projeto no console Firebase.
Vá para a página Modelos de e-mail na seção Auth.
Em qualquer uma das entradas Tipos de e-mail, clique no ícone de lápis para editar o modelo de e-mail.
Clique em Personalizar URL acionável e especifique o URL do gerenciador personalizado de ações de e-mail.

Depois de salvar o URL, ele será usado por todos os modelos de e-mail do projeto do Firebase.

Se estiver usando um domínio personalizado, mesmo que não esteja personalizando o gerenciador de ações de e-mail, talvez você queira concluir esta etapa para que os e-mails de gerenciamento de usuários sejam vinculados ao seu domínio em vez de serem vinculados ao domínio firebaseapp.com padrão.