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

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

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

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

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

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

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

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

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

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

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

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

  • عند معالجة الرابط في التطبيقات المصغّرة لإجراءات الويب، يكون هذا هو الرابط المؤدي إلى صفحة معيّنة في مَعلمة طلب البحث continueUrl.
  • عند معالجة الرابط في التطبيق مباشرةً، تكون هذه هي مَعلمة طلب البحث continueUrl في الرابط لصفحة في التطبيق "للرابط الديناميكي".
iOSBundleId سلسلة لضبط معرّف الحزمة سيؤدي ذلك إلى محاولة فتح الرابط في أحد تطبيقات Apple إذا كان مثبّتًا. يجب تسجيل التطبيق في Play Console. إذا لم يتم تقديم معرّف حزمة، يتم ضبط قيمة هذا الحقل على معرّف الحزمة للحزمة الرئيسية للتطبيق.
androidPackageName سلسلة تُستخدَم لضبط اسم حزمة Android. سيؤدي ذلك إلى محاولة فتح الرابط في تطبيق Android إذا كان مثبّتًا.
androidInstallApp قيمة منطقية (Bool) تُحدِّد ما إذا كان سيتم تثبيت تطبيق Android إذا كان الجهاز متوافقًا معه ولم يكن التطبيق مثبّتًا. في حال تقديم هذا الحقل بدون ملف برمجي packageName، يتم طرح خطأ يوضّح أنّه يجب تقديم ملف برمجي packageName مع هذا الحقل.
androidMinimumVersion سلسلة الحد الأدنى لإصدار التطبيق المتوافق مع هذه العملية إذا تم تحديد minimumVersion وتم تثبيت إصدار قديم من التطبيق، يتم توجيه المستخدم إلى "متجر Play" لترقية التطبيق. يجب تسجيل تطبيق Android في Console.
handleCodeInApp قيمة منطقية (Bool) ما إذا كان سيتم فتح رابط الإجراء في الرسالة الإلكترونية في تطبيق للأجهزة الجوّالة أو رابط على الويب أولاً. القيمة التلقائية هي false. عند ضبطها على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android، وسيفتحه التطبيق في حال تثبيته. في الحالة الخاطئة، سيتم إرسال الرمز إلى التطبيق المصغّر على الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند النقر على "متابعة" إذا كان مثبّتًا.
dynamicLinkDomain سلسلة (تم إيقافه نهائيًا، استخدِم linkDomain) لضبط نطاق الرابط الديناميكي (أو النطاق الفرعي) لاستخدامه مع الرابط الحالي إذا كان سيتم فتحه باستخدام "روابط Firebase الديناميكية". بما أنّه يمكن ضبط نطاقات ربط ديناميكة متعددة لكل مشروع، يوفر هذا الحقل إمكانية اختيار أحدها صراحةً. في حال عدم تقديم أي نطاق، يتم استخدام النطاق الأول تلقائيًا. linkDomain سلسلة نطاق استضافة Firebase المخصّص الاختياري لاستخدامه عند فتح الرابط من خلال تطبيق جوّال محدّد. يجب ضبط النطاق في "استضافة Firebase" وأن يكون مملوكًا للمشروع. لا يمكن أن يكون هذا النطاق هو نطاق استضافة تلقائي ("web.app" أو "firebaseapp.com"). ويحلّ هذا الإعداد محلّ الإعداد "dynamicLinkDomain" الذي تم إيقافه نهائيًا.

يوضّح المثال التالي كيفية إرسال رابط إثبات ملكية البريد الإلكتروني الذي سيتم فتحه في تطبيق متوافق مع الأجهزة الجوّالة أولاً كرابط ديناميكي في Firebase باستخدام example.page.link نطاق الرابط الديناميكي المخصّص (تطبيق iOS com.example.ios أو تطبيق Android com.example.android حيث سيتم تثبيت التطبيق إذا لم يكن مثبّتًا من قبل والحد الأدنى للإصدار هو 12). سيحتوي الرابط لصفحة معيّنة في التطبيق على الحمولة البرمجية لعنوان URL للمتابعة https://www.example.com/?email=user@example.com.

final user = FirebaseAuth.instance.currentUser;

final actionCodeSettings = ActionCodeSettings(
  url: "http://www.example.com/verify?email=${user?.email}",
  iOSBundleId: "com.example.ios",
  androidPackageName: "com.example.android",
);

await user?.sendEmailVerification(actionCodeSettings);

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

  1. فعِّل "روابط Firebase الديناميكية":

    1. في وحدة تحكُّم Firebase، افتح قسم الروابط الديناميكية.

    2. إذا لم تكن قد وافقت بعد على بنود الروابط الديناميكية وأنشأت ناحية برمجية لتطبيقك على الروابط الديناميكية، يُرجى إجراء ذلك الآن.

    3. إذا سبق لك إنشاء نطاق "روابط ديناميكية"، عليك تدوينه. يظهر نطاق الروابط الديناميكية عادةً بالشكل التالي: 

      example.page.link

    4. ستحتاج إلى هذه القيمة عند ضبط تطبيق Apple أو Android لمحاولة اعتراض الرابط الوافد.

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

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

  3. ضبط تطبيقات Apple:

    1. إذا كنت تخطّط للتعامل مع هذه الروابط من تطبيقك، يجب تحديد رقم تعريف الحِزمة في إعدادات مشروع وحدة تحكّم Firebase. بالإضافة إلى ذلك، يجب أيضًا تحديد رقم تعريف App Store ورقم تعريف فريق المطوّرين في Apple.
    2. ستحتاج أيضًا إلى ضبط نطاق الرابط العام لـ FDL على أنّه نطاق مرتبط في إمكانات تطبيقك.
    3. إذا كنت تخطط لتوزيع تطبيقك على الإصدار 8 من نظام التشغيل iOS والإصدارات الأقدم، ستحتاج إلى ضبط معرّف الحِزمة على أنّه مخطّط مخصّص لعناوين URL القادمة.
    4. لمزيد من المعلومات حول هذا الموضوع، يُرجى الرجوع إلى تعليمات تلقّي الروابط الديناميكية لمنصّات Apple.

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

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

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

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

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

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

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

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

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