حالة النجاح في إجراءات البريد الإلكتروني

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

يمكن أن يكون ذلك مفيدًا للغاية في السيناريوهات الشائعة التالية:

  • قد يحاول مستخدم لم يسجّل الدخول حاليًا الوصول إلى محتوى يتطلب تسجيل الدخول. ومع ذلك، قد يكون المستخدم قد نسى كلمة المرور، وبالتالي بدأ عملية إعادة ضبط كلمة المرور. في نهاية المسار، يتوقع المستخدم العودة إلى قسم التطبيق الذي كان يحاول الوصول إليه.

  • لا يمكن أن يمنح التطبيق إذن الوصول إلا إلى الحسابات التي تم إثبات ملكيتها. على سبيل المثال، قد تتطلّب النشرة الإخبارية من المستخدم إثبات ملكية عنوان بريده الإلكتروني قبل الاشتراك. سيخضع المستخدم لتدفق إثبات ملكية البريد الإلكتروني ويتوقع العودة إلى التطبيق لإكمال اشتراكه.

  • في حالات أخرى، قد يكون المستخدم قد بدأ عملية الإعداد من جهازه الجوّال ويتوقع بعد إثبات الهوية العودة إلى تطبيقه المتوافق مع الأجهزة الجوّالة بدلاً من المتصفح.

إنّ إمكانية تمرير الحالة من خلال عنوان URL للمتابعة هي ميزة فعّالة يوفّرها Firebase Auth ويمكن أن تحسِّن تجربة المستخدم بشكل كبير.

تمرير حالة عنوان URL للمتابعة في إجراءات الرسائل الإلكترونية

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

يجب تقديم مثيل firebase.auth.ActionCodeSettings عند إرسال رسالة إلكترونية لإعادة ضبط كلمة المرور أو رسالة إلكترونية لإثبات الهوية. تأخذ هذه الواجهة المَعلمات التالية:

المَعلمة النوع الوصف
url السلسلة

تُستخدَم لضبط الرابط (عنوان URL الخاص بالحالة/المواصلة) الذي له معانٍ مختلفة في سياقات مختلفة:

  • عند معالجة الرابط في التطبيقات المصغّرة لإجراءات الويب، يكون هذا هو الرابط العميق في مَعلمة طلب البحث continueUrl.
  • عند معالجة الرابط في التطبيق مباشرةً، تكون هذه هي مَعلمة طلب البحث continueUrl في الرابط لصفحة في التطبيق Hosting.
iOS ({bundleId: string}|undefined) لضبط معرّف حزمة iOS من أجل مساعدة Firebase Authentication في تحديد ما إذا كان يجب إنشاء رابط للويب فقط أو رابط للأجهزة الجوّالة يتم فتحه على جهاز Apple
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) لضبط اسم حزمة Android من أجل مساعدة Firebase Authentication في تحديد ما إذا كان ينبغي إنشاء رابط للويب فقط أو رابط للأجهزة الجوّالة يتم فتحه على جهاز Android
handleCodeInApp (boolean|undefined) ما إذا كان سيتم فتح رابط الإجراء في الرسالة الإلكترونية في تطبيق للأجهزة الجوّالة أو رابط على الويب أولاً. القيمة التلقائية هي false. عند ضبطها على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android، وسيفتحه التطبيق في حال تثبيته. في الحالة الخاطئة، سيتم إرسال الرمز إلى التطبيق المصغّر على الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند النقر على "متابعة" إذا كان مثبّتًا.
linkDomain (string|undefined) عند تحديد نطاقات روابط Hosting مخصّصة لمشروع معيّن، حدِّد النطاق الذي تريد استخدامه عندما يتم فتح الرابط من خلال تطبيق جوّال محدّد. بخلاف ذلك، يتم اختيار النطاق التلقائي تلقائيًا (مثل PROJECT_ID.firebaseapp.com).
dynamicLinkDomain (string|undefined) تمّ الإيقاف. لا تحدِّد هذه المَعلمة.

يوضّح المثال التالي كيفية إرسال رابط إثبات ملكية البريد الإلكتروني الذي سيتم فتحه في تطبيق متوافق مع الأجهزة الجوّالة أولاً باستخدام النطاق المخصّص Hosting custom-domain.com. سيحتوي الرابط لصفحة معيّنة في التطبيق على الحمولة لعنوان URL للمتابعة https://www.example.com/?email=user@example.com.

const actionCodeSettings = {
  url: 'https://www.example.com/?email=' + firebase.auth().currentUser.email,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
  },
  handleCodeInApp: true,
  // Specify a custom Hosting link domain to use. The domain must be
  // configured in Firebase Hosting and owned by the project.
  linkDomain: "custom-domain.com"
};
firebase.auth().currentUser.sendEmailVerification(actionCodeSettings)
  .then(function() {
    // Verification email sent.
  })
  .catch(function(error) {
    // Error occurred. Inspect error.code.
  });

يستخدم Firebase Authentication Firebase Hosting عند إرسال رابط مخصّص للفتح في تطبيق متوافق مع الأجهزة الجوّالة. لاستخدام هذه الميزة، يجب ضبط روابط الاستضافة في وحدة تحكّم Firebase.

  1. ضبط تطبيقات Android:

    1. إذا كنت تخطّط للتعامل مع هذه الروابط من تطبيق Android، يجب تحديد اسم حزمة تطبيقك في إعدادات مشروع Firebase console. بالإضافة إلى ذلك، يجب تقديم SHA-1 وSHA-256 لشهادة التطبيق.
    2. ستحتاج أيضًا إلى ضبط فلتر الأهداف لرابط الصفحة في التطبيق فيملفAndroidManifest.xml.
    3. لمزيد من المعلومات حول هذا الموضوع، يُرجى الرجوع إلى تعليمات تلقّي روابط استضافة التطبيقات على Android.

  2. ضبط تطبيقات iOS:

    1. إذا كنت تخطّط للتعامل مع هذه الروابط من تطبيقك المتوافق مع نظام التشغيل iOS، عليك ضبط نطاق رابط Hosting كنطاق مرتبط في إمكانات تطبيقك.
    2. لمزيد من المعلومات حول هذا الموضوع، يُرجى الرجوع إلى تعليمات تلقّي روابط استضافة التطبيقات على iOS.

معالجة إجراءات البريد الإلكتروني في تطبيق ويب

يمكنك تحديد ما إذا كنت تريد معالجة رابط رمز الإجراء من تطبيق ويب أولاً ثم إعادة التوجيه إلى صفحة ويب أخرى أو تطبيق جوّال بعد اكتمال العملية بنجاح، شرط توفّر التطبيق المتوافق مع الأجهزة الجوّالة. ويتم ذلك من خلال ضبط handleCodeInApp على false في كائن firebase.auth.ActionCodeSettings. على الرغم من أنّ معرّف حزمة iOS أو اسم حزمة Android ليسا مطلوبَين، فإنّ تقديمهما سيسمح للمستخدم بإعادة التوجيه إلى التطبيق المحدّد عند اكتمال رمز إجراء الرسالة الإلكترونية.

عنوان URL للويب المستخدَم هنا هو العنوان الذي تم ضبطه في القسم "نماذج إجراءات الرسائل الإلكترونية". يتم توفير نموذج تلقائي لجميع المشاريع. راجِع مقالة تخصيص معالجات البريد الإلكتروني لمعرفة المزيد من المعلومات عن كيفية تخصيص معالج إجراءات البريد الإلكتروني.

في هذه الحالة، سيكون الرابط ضمن مَعلمة طلب البحث continueUrl هو رابط استضافة تكون الحمولة فيه هي URL المحدّدة في عنصرActionCodeSettings.

عند معالجة إجراءات البريد الإلكتروني، مثل إثبات ملكية عنوان البريد الإلكتروني، يجب تحليل رمز الإجراء من مَعلمة طلب البحث oobCode من الرابط لصفحة معيّنة ثم تطبيقه من خلال applyActionCode لكي يتم تطبيق التغيير، أي إثبات ملكية عنوان البريد الإلكتروني.

معالجة إجراءات الرسائل الإلكترونية في تطبيق متوافق مع الأجهزة الجوّالة

يمكنك تحديد ما إذا كنت تريد معالجة رابط رمز الإجراء ضمن تطبيقك المتوافق مع الأجهزة الجوّالة أولاً، شرط أن يكون مثبّتًا. إذا تم النقر على الرابط من جهاز لا يتيح استخدام تطبيق الجوّال، سيتم فتحه من صفحة ويب بدلاً من ذلك. ويتم ذلك من خلال ضبط handleCodeInApp على true في كائن firebase.auth.ActionCodeSettings. يجب أيضًا تحديد اسم حزمة Android أو معرّف حزمة iOS للتطبيق المتوافق مع الأجهزة الجوّالة.

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

في هذه الحالة، سيكون رابط تطبيق الأجهزة الجوّالة الذي يتم إرساله إلى المستخدم هو رابط Hosting تتضمّن الحمولة عنوان URL لرمز الإجراء الذي تم ضبطه في وحدة التحكّم، مع مَعلمات الطلب oobCode وmode وapiKey وcontinueUrl. وسيكون هذا الأخير هو URL الأصلي المحدّد في عنصر ActionCodeSettings. يمكن تطبيق رمز الإجراء مباشرةً من تطبيق متوافق مع الأجهزة الجوّالة على غرار الطريقة التي يتم بها التعامل معه من مسار الويب الموضّح في القسم تخصيص معالجات الرسائل الإلكترونية.

عند معالجة إجراءات البريد الإلكتروني، مثل إثبات ملكية عنوان البريد الإلكتروني، يجب تحليل رمز الإجراء من مَعلمة طلب البحث oobCode من الرابط لصفحة معيّنة ثم تطبيقه من خلال applyActionCode لكي يتم تطبيق التغيير، أي إثبات ملكية عنوان البريد الإلكتروني.