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

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

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

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

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

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

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

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

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

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

Swift

المَعلمة	النوع	الوصف
URL	سلسلة	لضبط الرابط (عنوان URL للحالة/المتابعة) الذي يحمل معانٍ مختلفة في سياقات مختلفة: عند التعامل مع الرابط في أدوات إجراءات الويب، فإن هذا هو الموضع في معلَمة طلب البحث continueUrl. عند التعامل مع الرابط في التطبيق مباشرةً، هذا هو معلَمة طلب البحث "continueUrl" في الرابط لصفحة في التطبيق الرابط الديناميكي.
iOSBundleID	سلسلة	لضبط معرّف الحزمة. سيؤدي ذلك إلى محاولة فتح الرابط في أحد تطبيقات Apple إذا كان مثبّتًا. يجب تسجيل التطبيق في Console. إذا كانت الإجابة "لا" تم توفير معرِّف الحزمة، وتم تعيين قيمة هذا الحقل على معرِّف الحزمة الحزمة الرئيسية للتطبيق.
androidPackageName	سلسلة	لضبط اسم حزمة Android. سيؤدي هذا الإجراء إلى فتح الرابط في Android إذا كان مثبتًا.
androidInstallIfNotAvailable	منطقية	تُحدِّد ما إذا كان سيتم تثبيت تطبيق Android إذا كان الجهاز متوافقًا معه ولم يكن التطبيق مثبّتًا. إذا تم توفير هذا الحقل بدون packageName، تم حدوث خطأ يوضح أنه يجب تحديد packageName المقدمة مع هذا الحقل.
androidMinimumVersion	سلسلة	تمثّل هذه السمة الحد الأدنى من إصدار التطبيق المتوافق في هذا المسار. إذا تم تحديد minimumVersion وتم تثبيت إصدار قديم من التطبيق، يتم توجيه المستخدم إلى "متجر Play" لترقية التطبيق. يجب تسجيل تطبيق Android في Console.
handleCodeInApp	منطقية	ما إذا كان رابط إجراء البريد الإلكتروني سيتم فتحه في تطبيق للأجهزة الجوّالة أو على الويب أولاً. وتكون القيمة التلقائية false. وعند ضبطها على "صحيح"، يعمل رابط رمز الإجراء سيتم إرساله كرابط عام أو رابط تطبيق Android وسيتم فتحه. بواسطة التطبيق إذا كان مثبّتًا. في الحالة الخاطئة، سيتم إرسال الرمز إلى أداة تطبيقات الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند المتابعة إذا كان مثبّتًا.
dynamicLinkDomain	سلسلة	تضبط نطاق الرابط الديناميكي (أو النطاق الفرعي) لاستخدامه مع الرابط الحالي. إذا كان سيتم فتحه باستخدام روابط Firebase الديناميكية. كديناميكي متعدد يمكن ضبط نطاقات الروابط لكل مشروع، ويوفر هذا الحقل والقدرة على اختيار واحدة بشكل صريح. إذا لم يتم تقديم أي اسم، يتم تحديد النطاق الأول يُستخدم بشكل افتراضي.

Objective-C

المَعلمة	النوع	الوصف
URL	سلسلة NS	لضبط الرابط (عنوان URL للحالة/المتابعة) الذي يحمل معانٍ مختلفة في سياقات مختلفة: عند التعامل مع الرابط في أدوات إجراءات الويب، فإن هذا هو الموضع في معلَمة طلب البحث continueUrl. عند التعامل مع الرابط في التطبيق مباشرةً، هذا هو معلَمة طلب البحث "continueUrl" في الرابط لصفحة في التطبيق الرابط الديناميكي.
iOSBundleID	سلسلة NS	لضبط معرّف الحزمة. سيؤدي ذلك إلى محاولة فتح الرابط في أحد تطبيقات Apple إذا كان مثبّتًا. يجب تسجيل التطبيق في Console.
androidPackageName	سلسلة NS	لضبط اسم حزمة Android. سيؤدي هذا الإجراء إلى فتح الرابط في Android إذا كان مثبتًا.
androidInstallIfNotAvailable	BOOL	تُحدِّد ما إذا كان سيتم تثبيت تطبيق Android إذا كان الجهاز متوافقًا معه ولم يكن التطبيق مثبّتًا من قبل. إذا تم توفير هذا الحقل بدون packageName، تم حدوث خطأ يوضح أنه يجب تحديد packageName المقدمة مع هذا الحقل.
androidMinimumVersion	سلسلة NS	الحد الأدنى لإصدار التطبيق المتوافق مع هذه العملية في حال حذف تحديد الحد الأدنى للإصدار، وتم تثبيت إصدار قديم من التطبيق، يتم نقل المستخدم إلى متجر Play لترقية التطبيق. تطبيق Android أن يكون مسجَّلاً في Console
handleCodeInApp	BOOL	ما إذا كان رابط إجراء البريد الإلكتروني سيتم فتحه في تطبيق للأجهزة الجوّالة أو على الويب أولاً. وتكون القيمة التلقائية false. عند ضبطها على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android، وسيفتحه التطبيق في حال تثبيته. في الحالة الخاطئة، سيتم إرسال الرمز إلى أداة تطبيقات الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند النقر على "متابعة" إذا كان مثبّتًا.
dynamicLinkDomain	NSString	لضبط نطاق الرابط الديناميكي (أو النطاق الفرعي) المراد استخدامه للرابط الحالي إذا كان سيتم فتحه باستخدام "روابط Firebase الديناميكية". كديناميكي متعدد يمكن ضبط نطاقات الروابط لكل مشروع، ويوفر هذا الحقل والقدرة على اختيار واحدة بشكل صريح. إذا لم يتم تقديم أي اسم، يتم تحديد النطاق الأول يُستخدم بشكل افتراضي.

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

Swift

var actionCodeSettings =  ActionCodeSettings.init()
actionCodeSettings.canHandleInApp = true
let user = Auth.auth().currentUser()
actionCodeSettings.URL =
    String(format: "https://www.example.com/?email=%@", user.email)
actionCodeSettings.iOSbundleID = Bundle.main.bundleIdentifier!
actionCodeSettings.setAndroidPakageName("com.example.android",
                                         installIfNotAvailable:true,
                                         minimumVersion:"12")
// When multiple custom dynamic link domains are defined, specify which one to use.
actionCodeSettings.dynamicLinkDomain = "example.page.link"
user.sendEmailVerification(withActionCodeSettings:actionCodeSettings { error in
  if error {
    // Error occurred. Inspect error.code and handle error.
    return
  }
  // Email verification sent.
})

Objective-C

 FIRActionCodeSettings *actionCodeSettings = [[FIRActionCodeSettings alloc] init];
 actionCodeSettings.handleCodeInApp = YES;
 FIRUser *user = [FIRAuth auth].currentUser;
 NSString *urlString =
     [NSString stringWithFormat:@"https://www.example.com/?email=%@", user.email];
 actionCodeSettings.URL = [NSURL URLWithString:urlString];
 actionCodeSettings.iOSBundleID = [NSBundle mainBundle].bundleIdentifier;
 // When multiple custom dynamic link domains are defined, specify which one to use.
 actionCodeSettings.dynamicLinkDomain = @"example.page.link";
 [actionCodeSettings setAndroidPackageName:@"com.example.android"
                     installIfNotAvailable:YES
                            minimumVersion:'12'];
 [user sendEmailVerificationWithActionCodeSettings:actionCodeSettings
                                        completion:^(NSError *_Nullable error) {
   if (error) {
     // Error occurred. Inspect error.code and handle error.
     return;
   }
   // Email verification sent.
 }];

إعداد روابط Firebase الديناميكية

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

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

   1. في وحدة تحكّم Firebase، افتح قسم Dynamic Links.

   2. إذا لم يسبق لك قبول بنود Dynamic Links وإنشاء نطاق Dynamic Links ، يُرجى إجراء ذلك الآن.

      إذا سبق لك إنشاء نطاق Dynamic Links، يُرجى ملاحظة ذلك. يظهر نطاق Dynamic Links عادةً بالشكل التالي:

      example.page.link

      ستحتاج إلى هذه القيمة عند ضبط تطبيق 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 في كائن FIRActionCodeSettings (Obj-C) أو ActionCodeSettings (Swift). على الرغم من أنّه ليس مطلوبًا تحديد رقم تعريف الحزمة أو اسم حزمة Android، إلا أنّ تقديمهما سيسمح للمستخدم بإعادة التوجيه إلى التطبيق المحدّد عند اكتمال رمز إجراء البريد الإلكتروني.

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

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

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

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

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

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

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