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

ملاحظة: تستخدِم عملية التنفيذ القديمة لمصادقة الروابط عبر البريد الإلكتروني والإجراءات في إصدارات حزمة تطوير البرامج (SDK) الأقدم من الإصدار 23.2.0 من حزمة تطوير البرامج لنظام التشغيل Android والإصدار 11.8.0 من حزمة تطوير البرامج لنظام التشغيل iOS ميزة "الروابط الديناميكية من Firebase" التي سيتم إيقافها نهائيًا في 25 أغسطس 2025.

تم تعديل هذا الدليل للإشارة إلى الحلّ الجديد في إصدارات حزمة SDK اللاحقة.

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

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

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

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

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

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

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

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

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

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

Swift

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

Objective-C

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

يوضّح المثال التالي كيفية إرسال رابط تأكيد عبر البريد الإلكتروني سيتم فتحه أولاً في تطبيق على الجهاز الجوّال باستخدام نطاق الرابط المخصّص Hostingcustom-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. بالإضافة إلى ذلك، يجب تقديم خوارزميتَي 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 لرمز الإجراء، والذي تم إعداده في Play Console، مع مَعلمات طلب البحث oobCode وmode وapiKey وcontinueUrl. سيكون هذا الأخير هو URL الأصلي المحدّد في الكائن FIRActionCodeSettings (Obj-C) أو ActionCodeSettings (Swift). يمكن تطبيق رمز الإجراء مباشرةً من تطبيق على الجهاز الجوّال، على غرار طريقة التعامل معه من مسار الويب الموضّحة في قسم تخصيص معالجات البريد الإلكتروني.

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