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

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

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

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

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

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

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

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

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

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

المَعلمة النوع الوصف
url سلسلة

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

  • عندما تتم معالجة الرابط في أدوات الويب، يكون هذا هو الرابط لصفحة في التطبيق ضمن مَعلمة طلب البحث continueUrl.
  • عندما تتم معالجة الرابط في التطبيق مباشرةً، تكون هذه هي مَعلمة طلب البحث continueUrl في الرابط لصفحة في التطبيق الخاص بـ "الرابط الديناميكي".
iOSBundleId سلسلة تضبط هذه السمة معرّف الحزمة. سيحاول هذا الإجراء فتح الرابط في أحد تطبيقات Apple إذا كان مثبّتًا. يجب تسجيل التطبيق في Play Console. في حال عدم توفير معرّف الحزمة، يتم ضبط قيمة هذا الحقل على معرّف الحزمة الرئيسية للتطبيق.
androidPackageName سلسلة تضبط هذه السمة اسم حزمة Android. سيحاول هذا الإجراء فتح الرابط في تطبيق Android إذا كان مثبّتًا.
androidInstallApp bool تحدِّد هذه السمة ما إذا كان سيتم تثبيت تطبيق Android إذا كان الجهاز متوافقًا معه ولم يكن التطبيق مثبّتًا من قبل. إذا تم توفير هذا الحقل بدون packageName، سيظهر خطأ يوضّح أنّه يجب توفير packageName مع هذا الحقل.
androidMinimumVersion سلسلة الحد الأدنى لإصدار التطبيق المتوافق مع هذا المسار. في حال تحديد قيمة minimumVersion وتثبيت إصدار أقدم من التطبيق، سيتم توجيه المستخدم إلى "متجر Play" لترقية التطبيق. ويجب تسجيل تطبيق Android في Play Console.
handleCodeInApp bool تحديد ما إذا كان سيتم فتح رابط إجراء الرسالة الإلكترونية في تطبيق على الجهاز الجوّال أو رابط ويب أولاً القيمة التلقائية هي "خطأ". عند ضبط هذه السمة على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android وسيتم فتحه من خلال التطبيق إذا كان مثبّتًا. في الحالة غير الصحيحة، سيتم إرسال الرمز إلى التطبيق المصغّر على الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند المتابعة إذا كان مثبّتًا.
dynamicLinkDomain سلسلة (تم إيقافه نهائيًا، استخدِم linkDomain) يضبط نطاق الرابط الديناميكي (أو النطاق الفرعي) الذي سيتم استخدامه للرابط الحالي إذا كان سيتم فتحه باستخدام "روابط Firebase الديناميكية". بما أنّه يمكن ضبط نطاقات روابط ديناميكية متعدّدة لكل مشروع، يوفّر هذا الحقل إمكانية اختيار نطاق واحد بشكل صريح. في حال عدم توفير أي نطاق، يتم استخدام النطاق الأول تلقائيًا. linkDomain سلسلة نطاق Firebase Hosting المخصّص الاختياري الذي سيتم استخدامه عند فتح الرابط من خلال تطبيق محدّد على الأجهزة الجوّالة. يجب إعداد النطاق في Firebase Hosting وأن يكون المشروع هو مالكه. لا يمكن أن يكون هذا نطاق استضافة تلقائيًا (`web.app` أو `firebaseapp.com`). ويحلّ هذا الإعداد محلّ الإعداد المتوقّف نهائيًا `dynamicLinkDomain`.

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

final user = FirebaseAuth.instance.currentUser;

final actionCodeSettings = ActionCodeSettings(
  url: "http://www.example.com/verify?email=${user?.email}",
  iOSBundleId: "com.example.ios",
  androidPackageName: "com.example.android",
);

await user?.sendEmailVerification(actionCodeSettings);

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

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

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

    2. إذا لم تكن قد وافقت بعد على بنود خدمة Dynamic Links وأنشأت نطاقًا لـ Dynamic Links، عليك إجراء ذلك الآن.

    3. إذا سبق لك إنشاء نطاق Dynamic Links، سجِّله. عادةً ما يكون نطاق "روابط التطبيق الديناميكية" مشابهاً للمثال التالي: 

      example.page.link

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

  2. إعداد تطبيقات Android:

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

  3. إعداد تطبيقات Apple:

    1. إذا كنت تخطّط للتعامل مع هذه الروابط من تطبيقك، يجب تحديد معرّف الحزمة في إعدادات المشروع في "وحدة تحكّم Firebase". بالإضافة إلى ذلك، يجب تحديد رقم تعريف App Store ورقم تعريف فريق مطوّري Apple.
    2. عليك أيضًا ضبط نطاق الرابط العام لـ FDL كـ "نطاق مرتبط" في إمكانات تطبيقك.
    3. إذا كنت تخطّط لتوزيع تطبيقك على الإصدارات 8 من نظام التشغيل iOS والإصدارات الأقدم، عليك ضبط معرّف الحزمة كمخطّط مخصّص لعناوين URL الواردة.
    4. لمزيد من المعلومات حول هذا الموضوع، يُرجى الرجوع إلى تعليمات تلقّي الروابط الديناميكية على منصات Apple.

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

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

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

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

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

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

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

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

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