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

تؤدي بعض إجراءات إدارة المستخدمين، مثل تعديل عنوان البريد الإلكتروني للمستخدم وإعادة ضبط كلمة مرور المستخدم، إلى إرسال رسائل إلكترونية إليه. تحتوي الرسائل الإلكترونية هذه على روابط يمكن للمستلِمين فتحها لإكمال إجراء إدارة المستخدمين أو إلغائه. يتم تلقائيًا ربط الرسائل الإلكترونية المتعلّقة بإدارة المستخدمين بمعالج الإجراءات التلقائي، وهو صفحة ويب مستضافة على عنوان URL في نطاق استضافة Firebase الخاص بمشروعك.

يمكنك بدلاً من ذلك إنشاء واستضافة معالج إجراء مخصّص للبريد الإلكتروني من أجل إجراء معالجة مخصّصة ودمج معالج إجراء البريد الإلكتروني مع موقعك الإلكتروني.

تتطلب إجراءات إدارة المستخدمين التالية من المستخدم إكمال الإجراء باستخدام معالج إجراء البريد الإلكتروني:

• جارٍ إعادة ضبط كلمات المرور
• إلغاء تغييرات عناوين البريد الإلكتروني: عندما يغيّر المستخدمون عناوين البريد الإلكتروني الرئيسية لحساباتهم، يرسل Firebase رسالة إلكترونية إلى عناوينهم القديمة للسماح لهم بالتراجع عن التغيير
• إثبات ملكية عناوين البريد الإلكتروني

لتخصيص معالِج إجراء البريد الإلكتروني لمشروع Firebase، يجب إنشاء واستضافة صفحة ويب تستخدم حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصة بمشروع Firebase للتحقّق من صحة الطلب وإكمال الطلب. بعد ذلك، يجب تخصيص نماذج البريد الإلكتروني لمشروع Firebase لربطها بمعالج الإجراء المخصّص.

إنشاء صفحة "معالج إجراء البريد الإلكتروني"

1. يضيف Firebase العديد من معلَمات طلب البحث إلى عنوان URL لمعالج الإجراء عندما ينشئ رسائل إلكترونية لإدارة المستخدمين. مثلاً:

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

   تحدد هذه المعلمات مهمة إدارة المستخدم التي يكملها المستخدم. يجب أن تتعامل صفحة معالج إجراء البريد الإلكتروني مع معلمات طلب البحث التالية:

   المَعلمات
   الوضع	إجراء إدارة المستخدمين المطلوب إكماله. يمكن أن تكون القيمة إحدى القيم التالية: resetPassword recoverEmail verifyEmail
   رمز oobCode	رمز يُستخدم لمرة واحدة ويُستخدم لتحديد طلب والتحقق منه
   مفتاح واجهة برمجة التطبيقات	مفتاح واجهة برمجة التطبيقات لمشروع Firebase يتم توفيره لتسهيل الاستخدام
   عنوان URL للمتابعة	هذا عنوان URL اختياري يوفّر طريقة لتمرير الحالة إلى التطبيق مرة أخرى من خلال عنوان URL. ويرتبط ذلك بوضعَي "إعادة ضبط كلمة المرور" و"إثبات ملكية عنوان البريد الإلكتروني". عند إرسال رسالة إلكترونية لإعادة ضبط كلمة المرور أو رسالة تأكيد إلكترونية، يجب تحديد عنصر ActionCodeSettings باستخدام عنوان URL للمتابعة، وذلك لكي يتوفّر هذا العنصر. ويتيح ذلك للمستخدم المتابعة من حيث توقف مباشرةً بعد تنفيذ إجراء عبر البريد الإلكتروني.
   lang	هذه هي علامة اللغة الاختيارية BCP47 التي تمثّل لغة المستخدم (على سبيل المثال، fr). يمكنك استخدام هذه القيمة لتوفير صفحات معالجات إجراءات البريد الإلكتروني المترجَمة للمستخدمين. يمكن ضبط الترجمة باستخدام "وحدة تحكُّم Firebase" أو بشكل ديناميكي من خلال طلب واجهة برمجة تطبيقات العميل المقابلة قبل تشغيل إجراء الرسالة الإلكترونية. على سبيل المثال، باستخدام JavaScript: firebase.auth().languageCode = 'fr';. لتقديم تجربة مستخدم متّسقة، تأكَّد من أنّ أقلمة معالج إجراء الرسالة الإلكترونية تطابق ترجمة نماذج الرسالة الإلكترونية.

   يوضح المثال التالي كيفية التعامل مع معلمات طلب البحث في معالج يستند إلى المتصفح. (يمكنك أيضًا تنفيذ المعالج باعتباره تطبيق Node.js باستخدام منطق مماثل.)

   واجهة برمجة التطبيقات Web modular API

   مزيد من المعلومات حول واجهة برمجة تطبيقات الويب النموذجية التي يمكن تغيير عناصر التحكّم فيها والترقية من واجهة برمجة التطبيقات المخصّصة لمساحة الاسم

   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

   واجهة برمجة التطبيقات لمساحة الاسم على الويب

   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 modular API

   مزيد من المعلومات حول واجهة برمجة تطبيقات الويب النموذجية التي يمكن تغيير عناصر التحكّم فيها والترقية من واجهة برمجة التطبيقات المخصّصة لمساحة الاسم

   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

   واجهة برمجة التطبيقات لمساحة الاسم على الويب

   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 modular API

   مزيد من المعلومات حول واجهة برمجة تطبيقات الويب النموذجية التي يمكن تغيير عناصر التحكّم فيها والترقية من واجهة برمجة التطبيقات المخصّصة لمساحة الاسم

   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

   واجهة برمجة التطبيقات لمساحة الاسم على الويب

   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 modular API

   مزيد من المعلومات حول واجهة برمجة تطبيقات الويب النموذجية التي يمكن تغيير عناصر التحكّم فيها والترقية من واجهة برمجة التطبيقات المخصّصة لمساحة الاسم

   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

   واجهة برمجة التطبيقات لمساحة الاسم على الويب

   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.

بعد ذلك، عليك ضبط مشروع Firebase للربط بمعالج إجراء البريد الإلكتروني المخصّص في رسائل البريد الإلكتروني لإدارة المستخدمين.

رابط إلى المعالج المخصّص في نماذج الرسائل الإلكترونية

لضبط مشروع Firebase لاستخدام معالج إجراء البريد الإلكتروني المخصّص، يُرجى اتّباع الخطوات التالية:

1. افتح مشروعك في وحدة تحكُّم Firebase.
2. انتقِل إلى صفحة نماذج الرسائل الإلكترونية في قسم المصادقة.
3. في أي من أنواع البريد الإلكتروني، انقر على رمز القلم الرصاص لتعديل نموذج الرسالة الإلكترونية.
4. انقر على تخصيص عنوان URL للإجراء، وحدِّد عنوان URL لمعالج إجراء البريد الإلكتروني المخصّص.

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

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