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

برخی‌از کنش‌های مدیریت کاربر، مانند به‌روزرسانی نشانی ایمیل کاربر و بازنشانی گذرواژه کاربر، منجر به ارسال ایمیل به کاربر می‌شود. این ایمیل‌ها حاوی پیوندهایی هستند که گیرندگان می‌توانند آن‌ها را باز کنند تا کنش مدیریت کاربر را تکمیل یا لغو کنند. به‌طور پیش‌فرض، ایمیل‌های مدیریت کاربر به کنترل‌کننده کنش پیش‌فرض پیوند داده می‌شوند که صفحه وبی است که در نشانی وب دامنه «میزبانی Firebase» پروژه شما میزبانی می‌شود.

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

کنش‌های مدیریت کاربر زیر نیازمند این است که کاربر کنش را بااستفاده از گرداننده کنش ایمیل تکمیل کند:

• درحال بازنشانی گذرواژه‌ها
• لغو تغییرات نشانی ایمیل—وقتی کاربران نشانی‌های ایمیل اصلی حساب‌هایشان را تغییر می‌دهند، Firebase ایمیلی به نشانی‌های قدیمی آن‌ها ارسال می‌کند که به آن‌ها امکان می‌دهد تغییر را واگرد کنند
• درحال درستی‌سنجی نشانی‌های ایمیل

برای سفارشی‌سازی کردن مدیریت‌کننده کنش ایمیل پروژه Firebase، باید صفحه وبی ایجاد و میزبانی کنید که از «کیت توسعه نرم‌افزار جاوا اسکریپت Firebase» برای درستی‌سنجی اعتبار درخواست و تکمیل درخواست استفاده می‌کند. سپس باید الگوهای ایمیل پروژه Firebase خود را سفارشی‌سازی کنید تا به مدیریت‌کننده کنش سفارشی خود پیوند دهید.

ساختن صفحه مدیریت کنش ایمیل

1. وقتی Firebase ایمیل‌های مدیریت کاربر را تولید می‌کند، چندین پارامتر پُرسمان به نشانی وب مدیریت‌کننده کنش شما اضافه می‌کند. برای مثال:

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

   این پارامترها تکلیف مدیریت کاربری را که کاربر درحال تکمیل آن است مشخص می‌کنند. صفحه مدیریت کنش ایمیل شما باید پارامترهای پُرسمان زیر را مدیریت کند:

   پارامترها
   حالت	کنش مدیریت کاربر که باید تکمیل شود. می‌تواند یکی از مقادیر زیر باشد: resetPassword recoverEmail verifyEmail
   کد oob	کد یک‌بارمصرفی که برای شناسایی و درستی‌سنجی درخواست استفاده می‌شود
   کلید API	کلید API پروژه Firebase شما که برای راحتی ارائه شده است
   ادامهUrl	این نشانی وب اختیاری روشی برای انتقال وضعیت به برنامه ازطریق نشانی وب فراهم می‌کند. این موضوع مربوط به حالت‌های بازنشانی گذرواژه و درستی‌سنجی ایمیل است. هنگام ارسال ایمیل بازنشانی گذرواژه یا ایمیل درستی‌سنجی، باید یک هدف ActionCodeSettings با نشانی وب ادامه مشخص شود تا این ایمیل دردسترس قرار گیرد. این کار به کاربر امکان می‌دهد پس‌از انجام کنش ایمیل، از همان جایی که متوقف شده است ادامه دهد.
   lang	این برچسب زبان اختیاری 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 استفاده کنید.

عیب‌یابی: کلید میانای API قدیمی یا نامعتبر در پیوندهای کنش

پشتیبان «احراز هویت Firebase» کلید API جاسازی‌شده در پیوندهای کنش تولیدشده، مانند پارامتر apiKey در نشانی وب را مدیریت می‌کند. اگر کلیدهای API پروژه خود را بچرخانید یا کلیدی را که در ابتدا با Firebase Auth مرتبط بود حذف کنید، کاربران شما ممکن است پیوندهایی با کلیدهای نامعتبر دریافت کنند که منجر به خطاهای auth/invalid-api-key می‌شود.

برای حل‌وفصل این مشکل:

• اگر از «میزبانی Firebase» استفاده می‌کنید: کلید API ممکن است در init.json ذخیره شده باشد. نسخه جدیدی از سایت «میزبانی» (firebase deploy --only hosting) خود را پیاده‌سازی کنید تا سرویس فراداده‌های زیرینه را مجبور کنید پیکربندی را با کلید API فعال بازتولید کند.
• اگر خود کلید زیرینه نیاز به به‌روزرسانی دارد: ازآنجایی‌که نگاشت کلید API زیرینه را نمی‌توان مستقیماً بااستفاده از کنسول یا کیت‌های توسعه نرم‌افزار اصلاح کرد، باید با «پشتیبانی» تماس بگیرید و درخواست کنید پیکربندی اصالت‌سنجی زیرینه برای پروژه شما به‌روز شود.

سپس باید پروژه Firebase خود را پیکربندی کنید تا به مدیر اقدام ایمیل سفارشی شما در ایمیل‌های مدیریت کاربر پیوند دهد.

پیوند دادن به مدیریت‌کننده سفارشی در الگوهای ایمیل

برای پیکربندی پروژه Firebase خود برای استفاده از مدیریت‌کننده کنش ایمیل سفارشی:

1. در کنسول Firebase، به امنیت > اصالت‌سنجی > برگه الگوها بروید.

2. در هریک از ورودی‌های انواع ایمیل، روی نماد مداد کلیک کنید تا الگوی ایمیل را ویرایش کنید.

3. روی سفارشی‌سازی نشانی وب کنش کلیک کنید و نشانی وب را برای مدیریت‌کننده کنش ایمیل سفارشی‌تان مشخص کنید.

پس‌از ذخیره کردن نشانی وب، از آن در همه الگوهای ایمیل پروژه Firebase شما استفاده خواهد شد.