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

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

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

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

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

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

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

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

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

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

Swift

المَعلمة Type الوصف
URL String

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

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

Objective-C

المَعلمة Type الوصف
URL سلسلة NS

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

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

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

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" لاستخدام هذه الميزة.

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

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

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

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

      example.page.link

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

  2. تهيئة تطبيقات Android:

    1. وإذا أردت التعامل مع هذه الروابط من تطبيق Android، يجب تحديد اسم حزمة Android في إعدادات المشروع على "وحدة تحكُّم Firebase". بالإضافة إلى ذلك، يلزم تقديم خوارزمية 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" لكي يتم تطبيق التغيير، أي البريد الإلكتروني الذي يتم التحقّق منه.