کنترل کننده های اقدام ایمیل سفارشی ایجاد کنید

برخی از اقدامات مدیریت کاربر، مانند به‌روزرسانی آدرس ایمیل کاربر و تنظیم مجدد رمز عبور کاربر، منجر به ارسال ایمیل به کاربر می‌شود. این ایمیل‌ها حاوی پیوندهایی هستند که گیرندگان می‌توانند برای تکمیل یا لغو اقدام مدیریت کاربر، آنها را باز کنند. به طور پیش‌فرض، ایمیل‌های مدیریت کاربر به کنترل‌کننده‌ی پیش‌فرض عمل، که یک صفحه وب میزبانی شده در یک URL در دامنه‌ی Firebase Hosting پروژه‌ی شما است، پیوند می‌دهند.

در عوض، می‌توانید یک کنترل‌کننده‌ی عملیات ایمیل سفارشی ایجاد و میزبانی کنید تا پردازش‌های سفارشی انجام دهد و کنترل‌کننده‌ی عملیات ایمیل را با وب‌سایت شما ادغام کند.

اقدامات مدیریت کاربر زیر مستلزم آن است که کاربر با استفاده از یک کنترل‌کننده‌ی عملیات ایمیل، اقدام را تکمیل کند:

• بازنشانی رمزهای عبور
• لغو تغییرات آدرس ایمیل - وقتی کاربران آدرس‌های ایمیل اصلی حساب‌های خود را تغییر می‌دهند، Firebase ایمیلی به آدرس‌های قدیمی آنها ارسال می‌کند که به آنها امکان می‌دهد تغییر را لغو کنند.
• تأیید آدرس‌های ایمیل

برای سفارشی‌سازی کنترل‌کننده‌ی عملیات ایمیل پروژه‌ی فایربیس خود، باید یک صفحه‌ی وب ایجاد و میزبانی کنید که از کیت توسعه‌ی نرم‌افزار جاوااسکریپت فایربیس برای تأیید اعتبار درخواست و تکمیل آن استفاده کند. سپس، باید قالب‌های ایمیل پروژه‌ی فایربیس خود را طوری سفارشی کنید که به کنترل‌کننده‌ی عملیات سفارشی شما لینک شوند.

صفحه مدیریت عملیات ایمیل را ایجاد کنید

1. فایربیس هنگام تولید ایمیل‌های مدیریت کاربر، چندین پارامتر کوئری به آدرس URL مربوط به action handler شما اضافه می‌کند. برای مثال:

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

   این پارامترها وظیفه مدیریت کاربر را که کاربر در حال انجام آن است، مشخص می‌کنند. صفحه مدیریت عملیات ایمیل شما باید پارامترهای پرس و جوی زیر را مدیریت کند:

   پارامترها
   حالت	اقدام مدیریت کاربر که باید تکمیل شود. می‌تواند یکی از مقادیر زیر باشد: resetPassword recoverEmail verifyEmail
   اوب‌کد	یک کد یکبار مصرف، که برای شناسایی و تأیید درخواست استفاده می‌شود
   کلید API	کلید API پروژه Firebase شما، که برای راحتی ارائه شده است
   ادامهآدرس	این یک URL اختیاری است که راهی برای ارسال وضعیت به برنامه از طریق URL فراهم می‌کند. این مربوط به حالت‌های بازنشانی رمز عبور و تأیید ایمیل است. هنگام ارسال ایمیل بازنشانی رمز عبور یا ایمیل تأیید، باید یک شیء ActionCodeSettings با یک URL ادامه مشخص شود تا این قابلیت در دسترس باشد. این امر به کاربر امکان می‌دهد تا پس از یک اقدام ایمیل، درست از جایی که متوقف شده بود، ادامه دهد.
   لنگ	این یک برچسب زبان اختیاری BCP47 است که نشان‌دهنده زبان کاربر (مثلاً fr ) است. می‌توانید از این مقدار برای ارائه صفحات کنترل‌کننده عملیات ایمیل محلی به کاربران خود استفاده کنید. محلی‌سازی را می‌توان از طریق کنسول Firebase یا به صورت پویا با فراخوانی API کلاینت مربوطه قبل از اجرای عملیات ایمیل تنظیم کرد. برای مثال، با استفاده از جاوا اسکریپت: firebase.auth().languageCode = 'fr'; . برای تجربه کاربری پایدار، مطمئن شوید که محلی‌سازی کنترل‌کننده عملیات ایمیل با قالب ایمیل مطابقت دارد.

   مثال زیر نشان می‌دهد که چگونه می‌توانید پارامترهای پرس‌وجو را در یک هندلر مبتنی بر مرورگر مدیریت کنید. (همچنین می‌توانید هندلر را به عنوان یک برنامه 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، توسط تمام قالب‌های ایمیل پروژه Firebase شما استفاده خواهد شد.

اگر از یک دامنه سفارشی استفاده می‌کنید، حتی اگر کنترل‌کننده عملیات ایمیل خود را سفارشی نمی‌کنید، ممکن است بخواهید این مرحله را انجام دهید تا ایمیل‌های مدیریت کاربر به جای دامنه پیش‌فرض firebaseapp.com به دامنه شما پیوند داده شوند.