إنشاء معالجات إجراءات بريد إلكتروني مخصّصة

تؤدي بعض إجراءات إدارة المستخدمين، مثل تعديل عنوان البريد الإلكتروني للمستخدم وإعادة ضبط كلمة المرور، إلى إرسال رسائل إلكترونية إلى المستخدم. تحتوي هذه الرسائل الإلكترونية على روابط يمكن للمستلمين فتحها لإكمال إجراء إدارة المستخدمين أو إلغائه. تتضمّن رسائل البريد الإلكتروني لإدارة المستخدمين بشكلٍ تلقائي رابطًا إلى معالج الإجراءات التلقائي، وهو عبارة عن صفحة ويب مستضافة على عنوان 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	مفتاح واجهة برمجة التطبيقات لمشروعك على Firebase، ويتم توفيره لتسهيل الأمر عليك
   continueUrl	هذا عنوان URL اختياري يوفّر طريقة لإعادة الحالة إلى التطبيق من خلال عنوان URL. وينطبق ذلك على أوضاع إعادة ضبط كلمة المرور وتأكيد عنوان البريد الإلكتروني. عند إرسال رسالة إلكترونية لإعادة ضبط كلمة المرور أو رسالة إلكترونية لتأكيد الحساب، يجب تحديد عنصر ActionCodeSettings مع متابعة عنوان URL لكي يكون متاحًا. يتيح ذلك للمستخدم مواصلة العمل من حيث توقّف بعد اتّخاذ إجراء عبر البريد الإلكتروني.
   lang	هذه هي علامة اللغة الاختيارية BCP47 التي تمثّل اللغة المحلية للمستخدم (على سبيل المثال، fr). يمكنك استخدام هذه القيمة لتوفير صفحات معالجة الإجراءات عبر البريد الإلكتروني بلغة المستخدمين. يمكن ضبط اللغة من خلال "وحدة تحكّم Firebase" أو بشكل ديناميكي من خلال استدعاء واجهة برمجة التطبيقات المناسبة من جهة العميل قبل بدء إجراء إرسال الرسالة الإلكترونية. على سبيل المثال، باستخدام JavaScript: 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، انتقِل إلى علامة التبويب قوالب ضمن الأمان > المصادقة.

2. في أي من إدخالات أنواع الرسائل الإلكترونية، انقر على رمز القلم الرصاص لتعديل نموذج الرسالة الإلكترونية.

3. انقر على تخصيص عنوان URL للإجراء، وحدِّد عنوان URL لمعالج إجراءات عنوان بريد إلكتروني في نطاق خاص.

بعد حفظ عنوان URL، سيتم استخدامه في جميع نماذج الرسائل الإلكترونية الخاصة بمشروعك على Firebase.

إذا كنت تستخدم نطاقًا مخصّصًا، حتى إذا لم تكن تخصّص معالج إجراءات البريد الإلكتروني، قد تحتاج إلى إكمال هذه الخطوة حتى ترتبط رسائل البريد الإلكتروني الخاصة بإدارة المستخدمين بنطاقك بدلاً من النطاق التلقائي firebaseapp.com.