יצירת רכיבי handler מותאמים אישית לפעולות באימייל

חלק מהפעולות לניהול משתמשים, כמו עדכון כתובת האימייל של משתמש ואיפוס הסיסמה של משתמש, גורמות לשליחת אימיילים למשתמש. האימיילים האלה מכילים קישורים שהנמענים יכולים לפתוח כדי להשלים או לבטל את פעולת ניהול המשתמש. כברירת מחדל, האימיילים לניהול משתמשים מקשרים ל-handler של פעולת ברירת המחדל, שהוא דף אינטרנט שמתארח בכתובת URL בדומיין של אירוח ב-Firebase של הפרויקט.

במקום זאת, אתם יכולים ליצור ולארח handler מותאם אישית לפעולות באימייל כדי לבצע עיבוד מותאם אישית ולשלב את ה-handler לפעולות באימייל עם האתר שלכם.

כדי לבצע את הפעולות הבאות לניהול משתמשים, המשתמש צריך להשתמש בטיפול בפעולות באימייל:

• איפוס סיסמאות
• ביטול שינויים בכתובות אימייל – כשמשתמשים משנים את כתובות האימייל הראשיות בחשבונות שלהם, Firebase שולחת אימייל לכתובות הישנות שלהם, שמאפשר להם לבטל את השינוי.
• אימות כתובות אימייל

כדי להתאים אישית את ה-handler של פעולות באימייל בפרויקט Firebase, צריך ליצור ולארח דף אינטרנט שמשתמש ב-Firebase JavaScript SDK כדי לאמת את התוקף של הבקשה ולהשלים אותה. לאחר מכן, צריך להתאים אישית את תבניות האימייל של פרויקט Firebase כדי לקשר אותן ל-handler של הפעולה המותאמת אישית.

יצירת דף לטיפול בפעולות באימייל

1. מערכת Firebase מוסיפה כמה פרמטרים של שאילתות לכתובת ה-URL של ה-handler של הפעולה כשהיא יוצרת אימיילים לניהול משתמשים. לדוגמה:

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

   הפרמטרים האלה מציינים את משימת ניהול המשתמשים שהמשתמש משלים. דף הטיפול בפעולות באימייל צריך לטפל בפרמטרים הבאים של השאילתה:

   פרמטרים
   מצב	פעולת ניהול המשתמשים שצריך להשלים. יכול להיות אחד מהערכים הבאים: resetPassword recoverEmail verifyEmail
   oobCode	קוד חד-פעמי שמשמש לזיהוי ולאימות של בקשה
   apiKey	מפתח ה-API של פרויקט Firebase, שמופיע כאן לנוחותכם
   continueUrl	זוהי כתובת URL אופציונלית שמאפשרת להעביר את הסטטוס בחזרה לאפליקציה באמצעות כתובת URL. זה רלוונטי למצבים של איפוס סיסמה ואימות אימייל. כששולחים אימייל לאיפוס סיסמה או הודעת אימות, צריך לציין אובייקט ActionCodeSettings עם כתובת URL להמשך כדי שהאפשרות הזו תהיה זמינה. כך משתמש יכול להמשיך בדיוק מהמקום שבו הוא הפסיק אחרי פעולה באימייל.
   lang	זהו תג שפה אופציונלי BCP47 שמייצג את הלוקאל של המשתמש (לדוגמה, fr). אפשר להשתמש בערך הזה כדי לספק למשתמשים דפים של מטפלי פעולות באימייל שמותאמים לשפה שלהם. אפשר להגדיר לוקליזציה דרך Firebase Console או באופן דינמי על ידי קריאה ל-API המתאים של הלקוח לפני הפעלת פעולת האימייל. לדוגמה, באמצעות JavaScript: firebase.auth().languageCode = 'fr';. כדי להבטיח חוויית משתמש עקבית, חשוב לוודא שהלוקליזציה של רכיב ה-handler של פעולת האימייל תואמת ללוקליזציה של תבנית האימייל.

   בדוגמה הבאה אפשר לראות איך מטפלים בפרמטרים של השאילתה ב-handler מבוסס-דפדפן. (אפשר גם להטמיע את ה-handler כאפליקציית Node.js באמצעות לוגיקה דומה).

   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. כדי לטפל בבקשות לאיפוס סיסמה, צריך קודם לאמת את קוד הפעולה באמצעות verifyPasswordResetCode, ואז לקבל סיסמה חדשה מהמשתמש ולהעביר אותה אל confirmPasswordReset. לדוגמה:

   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. כדי לבטל שינוי של כתובת אימייל, קודם צריך לאמת את קוד הפעולה באמצעות checkActionCode, ואז לשחזר את כתובת האימייל של המשתמש באמצעות applyActionCode. לדוגמה:

   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. צריך לטפל באימות של כתובת האימייל על ידי התקשרות אל applyActionCode. לדוגמה:

   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. מאחסנים את הדף במקום כלשהו, למשל באמצעות Firebase Hosting.

לאחר מכן, צריך להגדיר את פרויקט Firebase כך שיקשר לטיפול המותאם אישית בפעולות באימייל בהודעות האימייל לניהול משתמשים.

קישור לטיפול בהתאמה אישית בתבניות אימייל

כדי להגדיר את פרויקט Firebase כך שישתמש בטיפול המותאם אישית בפעולות שקשורות לאימייל:

1. במסוף Firebase, עוברים אל Security (אבטחה) > Authentication (אימות) > הכרטיסייה Templates (תבניות).

2. באחת מהרשומות של סוגי אימייל, לוחצים על סמל העיפרון כדי לערוך את תבנית האימייל.

3. לוחצים על התאמה אישית של כתובת ה-URL של הפעולה ומציינים את כתובת ה-URL של ה-handler של פעולת האימייל המותאמת אישית.

אחרי שתשמרו את כתובת ה-URL, היא תשמש את כל תבניות האימייל של פרויקט Firebase.