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

تحذير: ستتأثّر الميزات الثلاث التالية من Firebase Authentication بإيقاف Firebase Dynamic Links نهائيًا في 25 آب (أغسطس) 2025: مصادقة رابط البريد الإلكتروني للتطبيقات المتوافقة مع الأجهزة الجوّالة، ومسارات OAuth لتطبيقات Android التي تستخدم إصدارات قديمة من حزمة SDK لنظام التشغيل Authentication، وتوافق بروتوكول OAuth مع مكتبة Cordova لتطبيقات الويب. لاستخدام هذه الميزات بعد إيقاف Dynamic Links، عليك نقل البيانات لاستخدام إصدار أحدث من حزمة SDK وإكمال بعض الخطوات الإضافية.

للحصول على معلومات محدّدة وإرشادات حول نقل البيانات، يُرجى الانتقال إلى مقالة Dynamic Links الأسئلة الشائعة حول الإيقاف النهائي.

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

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

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

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

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

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

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

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

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

Swift

المَعلمة	النوع	الوصف
URL	سلسلة	تُستخدَم لضبط الرابط (عنوان URL الخاص بالحالة/المواصلة) الذي له معانٍ مختلفة في سياقات مختلفة: عند معالجة الرابط في التطبيقات المصغّرة لإجراءات الويب، يكون هذا هو الرابط العميق في مَعلمة طلب البحث continueUrl. عند معالجة الرابط في التطبيق مباشرةً، تكون هذه هي مَعلمة طلب البحث continueUrl في الرابط لصفحة في التطبيق Hosting.
iOSBundleID	سلسلة	لضبط معرّف حزمة iOS من أجل مساعدة Firebase Authentication في تحديد ما إذا كان يجب إنشاء رابط للويب فقط أو رابط للأجهزة الجوّالة يتم فتحه على جهاز Apple
androidPackageName	سلسلة	لضبط اسم حزمة Android من أجل مساعدة Firebase Authentication في تحديد ما إذا كان ينبغي إنشاء رابط للويب فقط أو رابط للأجهزة الجوّالة يتم فتحه على جهاز Android
handleCodeInApp	منطقية	ما إذا كان سيتم فتح رابط الإجراء في الرسالة الإلكترونية في تطبيق للأجهزة الجوّالة أو رابط على الويب أولاً. القيمة التلقائية هي false. عند ضبطها على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android، وسيفتحه التطبيق في حال تثبيته. في الحالة الخاطئة، سيتم إرسال الرمز إلى التطبيق المصغّر على الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند النقر على "متابعة" إذا كان مثبّتًا.
linkDomain	سلسلة	عند تحديد نطاقات روابط استضافة مخصّصة لمشروع معيّن، حدِّد النطاق الذي تريد استخدامه عندما يتم فتح الرابط من خلال تطبيق مخصّص للأجهزة الجوّالة. بخلاف ذلك، يتم اختيار النطاق التلقائي تلقائيًا (مثل PROJECT_ID.firebaseapp.com).
dynamicLinkDomain	سلسلة	تمّ الإيقاف. لا تحدِّد هذه المَعلمة.

Objective-C

المَعلمة	النوع	الوصف
URL	NSString	تُستخدَم لضبط الرابط (عنوان URL الخاص بالحالة/المواصلة) الذي له معانٍ مختلفة في سياقات مختلفة: عند معالجة الرابط في التطبيقات المصغّرة لإجراءات الويب، يكون هذا هو الرابط العميق في مَعلمة طلب البحث continueUrl. عند معالجة الرابط في التطبيق مباشرةً، تكون هذه هي مَعلمة طلب البحث continueUrl في الرابط لصفحة في التطبيق Hosting.
iOSBundleID	NSString	ضبط معرّف حزمة iOS لمساعدة Firebase Authentication في تحديد ما إذا كان ينبغي إنشاء رابط مخصّص للويب فقط أو للأجهزة الجوّالة يتم فتحه على جهاز Android أو Apple
androidPackageName	NSString	لضبط اسم حزمة Android من أجل مساعدة Firebase Authentication في تحديد ما إذا كان ينبغي إنشاء رابط مخصّص للويب فقط أو للأجهزة الجوّالة يتم فتحه على جهاز Android أو Apple
handleCodeInApp	BOOL	ما إذا كان سيتم فتح رابط الإجراء في الرسالة الإلكترونية في تطبيق للأجهزة الجوّالة أو رابط على الويب أولاً. القيمة التلقائية هي false. عند ضبطها على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android، وسيفتحه التطبيق في حال تثبيته. في الحالة الخاطئة، سيتم إرسال الرمز إلى التطبيق المصغّر على الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند النقر على "متابعة" إذا كان مثبّتًا.
linkDomain	NSString	عند تحديد نطاقات روابط Hosting مخصّصة لمشروع معيّن، حدِّد النطاق الذي تريد استخدامه عندما يتم فتح الرابط من خلال تطبيق جوّال محدّد. بخلاف ذلك، يتم اختيار النطاق التلقائي تلقائيًا (مثل PROJECT_ID.firebaseapp.com).
dynamicLinkDomain	NSString	تمّ الإيقاف. لا تحدِّد هذه المَعلمة.

يوضّح المثال التالي كيفية إرسال رابط إثبات ملكية البريد الإلكتروني الذي سيتم فتحه في تطبيق متوافق مع الأجهزة الجوّالة أولاً باستخدام نطاق الرابط المخصّص Hosting custom-domain.com. سيحتوي الرابط لصفحة معيّنة في التطبيق على الحمولة لعنوان 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")
// Specify a custom Hosting link domain to use. The domain must be
// configured in Firebase Hosting and owned by the project.
actionCodeSettings.linkDomain = "custom-domain.com"
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;
// Specify a custom Hosting link domain to use. The domain must be
// configured in Firebase Hosting and owned by the project.
 actionCodeSettings.linkDomain = @"custom-domain.com";
 [actionCodeSettings setAndroidPackageName:@"com.example.android"];
 [user sendEmailVerificationWithActionCodeSettings:actionCodeSettings
                                        completion:^(NSError *_Nullable error) {
   if (error) {
     // Error occurred. Inspect error.code and handle error.
     return;
   }
   // Email verification sent.
 }];

ضبط روابط Firebase Hosting

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

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

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

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

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

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

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

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

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

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

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

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

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

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