Crea gestori di azioni email personalizzate

Alcune azioni di gestione degli utenti, come l'aggiornamento dell'indirizzo email e il ripristino della password, comportano l'invio di email all'utente. Queste email contengono link che i destinatari possono aprire per completare o annullare l'azione di gestione utenti. Per impostazione predefinita, le email di gestione degli utenti rimandano al gestore di azioni predefinito, ovvero una pagina web ospitata a un URL nel dominio Firebase Hosting del tuo progetto.

In alternativa, puoi creare e ospitare un gestore di azioni email personalizzato per eseguire l'elaborazione personalizzata e integrare il gestore di azioni email con il tuo sito web.

Le seguenti azioni di gestione utenti richiedono all'utente di completare l'azione utilizzando un gestore di azioni email:

• Reimpostazione delle password
• Revoca delle modifiche all'indirizzo email: quando gli utenti modificano gli indirizzi email principali dei propri account, Firebase invia un'email ai loro vecchi indirizzi che consente di annullare la modifica
• Verifica degli indirizzi email

Per personalizzare il gestore delle azioni email del progetto Firebase, devi creare e ospitare una pagina web che utilizzi l'SDK JavaScript di Firebase per verificare la validità della richiesta e completarla. Poi, devi personalizzare i modelli email del progetto Firebase per collegarli al gestore di azioni personalizzato.

Crea la pagina del gestore delle azioni email

1. Firebase aggiunge diversi parametri di query all'URL del gestore di azioni quando genera email di gestione degli utenti. Ad esempio:

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

   Questi parametri specificano l'attività di gestione utenti che l'utente sta completando. La pagina del gestore delle azioni email deve gestire i seguenti parametri della query:

   Parametri
   modalità	L'azione di gestione utenti da completare. Può avere uno dei seguenti valori: resetPassword recoverEmail verifyEmail
   oobCode	Un codice monouso, utilizzato per identificare e verificare una richiesta
   apiKey	La chiave API del tuo progetto Firebase, fornita per comodità
   continueUrl	Si tratta di un URL facoltativo che consente di trasmettere lo stato all'app tramite un URL. Ciò è pertinente alle modalità di reimpostazione della password e di verifica dell'email. Quando invii un'email di reimpostazione della password o di verifica, è necessario specificare un oggetto ActionCodeSettings con un URL di continuazione per renderlo disponibile. In questo modo, un utente può continuare esattamente da dove aveva interrotto dopo un'azione email.
   lang	Questo è il tag di lingua BCP47 facoltativo che rappresenta le impostazioni internazionali dell'utente (ad esempio, fr). Puoi utilizzare questo valore per fornire pagine di gestione delle azioni email localizzate ai tuoi utenti. La localizzazione può essere impostata tramite la console Firebase o dinamicamente chiamando l'API client corrispondente prima di attivare l'azione email. Ad esempio, utilizzando JavaScript: firebase.auth().languageCode = 'fr';. Per un'esperienza utente coerente, assicurati che la localizzazione del gestore di azioni email corrisponda a quella del modello di email.

   Il seguente esempio mostra come gestire i parametri di query in un gestore basato su browser. (Potresti anche implementare il gestore come applicazione Node.js utilizzando una logica simile).

   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

2. Gestisci le richieste di reimpostazione della password verificando prima il codice azione con verifyPasswordResetCode, poi ottieni una nuova password dall'utente e passala a confirmPasswordReset. Ad esempio:

   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

3. Gestisci le revoche della modifica dell'indirizzo email verificando prima il codice azione con checkActionCode, poi ripristina l'indirizzo email dell'utente con applyActionCode. Ad esempio:

   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

4. Gestisci la verifica dell'indirizzo email chiamando il numero applyActionCode. Ad esempio:

   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

5. Ospita la pagina da qualche parte, ad esempio utilizza Firebase Hosting.

Risoluzione dei problemi: chiave API obsoleta o non valida nei link delle azioni

Il backend di Firebase Authentication gestisce la chiave API incorporata nei link di azione generati, ad esempio il parametro apiKey nell'URL. Se ruoti le chiavi API del tuo progetto o elimini la chiave originariamente associata a Firebase Auth, i tuoi utenti potrebbero ricevere link con chiavi non valide, con conseguenti errori auth/invalid-api-key.

Per risolvere il problema:

• Se utilizzi Firebase Hosting:la chiave API potrebbe essere memorizzata nella cache in init.json. Esegui il deployment di una nuova versione del tuo sito di hosting (firebase deploy --only hosting) per forzare la rigenerazione della configurazione da parte del servizio di metadati di backend con la chiave API attiva.
• Se è necessario aggiornare la chiave di backend: poiché il mapping della chiave API di backend non può essere modificato direttamente utilizzando la console o gli SDK, devi contattare l'assistenza per richiedere un aggiornamento della configurazione di autenticazione di backend per il tuo progetto.

Successivamente, devi configurare il progetto Firebase in modo che si colleghi al gestore di azioni email personalizzato nelle email di gestione degli utenti.

Link al gestore personalizzato nei modelli email

Per configurare il progetto Firebase in modo da utilizzare il tuo gestore di azioni email personalizzato:

1. Nella console Firebase, vai alla scheda Sicurezza > Autenticazione > Modelli.

2. In una qualsiasi delle voci Tipi di email, fai clic sull'icona a forma di matita per modificare il modello di email.

3. Fai clic su Personalizza l'URL di azione e specifica l'URL del gestore di azioni email personalizzato.

Una volta salvato l'URL, verrà utilizzato da tutti i modelli email del tuo progetto Firebase.