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

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

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

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

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

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

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

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

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

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

سويفت

معامل يكتب وصف
URL خيط

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

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

ج موضوعية

معامل يكتب وصف
URL NSString

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

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

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

سويفت


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.
})

ج موضوعية

 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 Auth روابط Firebase الديناميكية عند إرسال رابط يُقصد فتحه في تطبيق الهاتف المحمول. لاستخدام هذه الميزة، يجب تكوين الارتباطات الديناميكية في وحدة تحكم Firebase.

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

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

      إذا قمت بالفعل بإنشاء مجال الارتباطات الديناميكية، فلاحظ ذلك. عادةً ما يبدو مجال الارتباطات الديناميكية كالمثال التالي:

      example.page.link

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

  2. تكوين تطبيقات أندرويد:

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

    1. إذا كنت تخطط للتعامل مع هذه الروابط من تطبيقك، فيجب تحديد معرف الحزمة في إعدادات مشروع Firebase Console. بالإضافة إلى ذلك، يجب أيضًا تحديد معرف متجر التطبيقات ومعرف فريق مطوري Apple.
    2. ستحتاج أيضًا إلى تكوين مجال الارتباط العالمي FDL كمجال مرتبط في إمكانيات التطبيق لديك.
    3. إذا كنت تخطط لتوزيع تطبيقك على إصدار iOS 8 أو أقل، فستحتاج إلى تعيين معرف الحزمة الخاص بك كمخطط مخصص لعناوين 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 ليصبح التغيير ساري المفعول، أي ليتم التحقق من البريد الإلكتروني.