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

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

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

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

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

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

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

   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 או באופן דינמי על ידי קריאה לממשק ה-API המתאים של הלקוח לפני הפעלת הפעולה של שליחת האימייל. לדוגמה, באמצעות JavaScript: firebase.auth().languageCode = 'fr';. כדי שחוויית המשתמש תהיה עקבית, חשוב לוודא שהתרגום של פונקציית הטיפול בפעולות באימייל תואם לתרגום של תבנית האימייל.

   בדוגמה הבאה אפשר לראות איך אפשר לטפל בפרמטרים של השאילתה ב-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.
2. עוברים לדף Email Templates בקטע Auth.
3. בכל אחת מהאפשרויות בקטע Email Types, לוחצים על סמל העיפרון כדי לערוך את תבנית האימייל.
4. לוחצים על customize action URL (התאמה אישית של כתובת ה-URL של הפעולה) ומציינים את כתובת ה-URL של פונקציית הטיפול בהודעות האימייל בהתאמה אישית.

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