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

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

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

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

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

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

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

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

لتمرير عنوان URL للمتابعة بأمان، عليك إضافة نطاق عنوان URL كنطاق مُرخَّص:

  1. في وحدة تحكُّم Firebase، انتقِل إلى علامة التبويب الأمان > المصادقة > الإعدادات.

  2. في قسم النطاقات المُرخَّصة ، انقر على إضافة نطاق، وأضِف عنوان URL.

يجب توفير مثيل 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) ما إذا كان سيتم فتح رابط إجراء البريد الإلكتروني في تطبيق الأجهزة الجوّالة أو رابط الويب أولاً. وتكون القيمة التلقائية مضبوطة على false. عند ضبط هذه المَعلمة على true، سيتم إرسال رابط رمز الإجراء سيتم إرساله كرابط عام أو رابط تطبيق Android وسيتم فتحه من خلال التطبيق إذا كان مثبّتًا. في حال ضبط هذه المَعلمة على false، سيتم إرسال الرمز إلى الـ أداة واجهة المستخدم على الويب أولاً، ثم سيتم إعادة التوجيه إلى التطبيق إذا كان مثبّتًا عند النقر على "متابعة".
dynamicLinkDomain سلسلة (تم إيقاف هذه الميزة، يُرجى استخدام `linkDomain`) يضبط هذا الإجراء نطاق (أو نطاقًا فرعيًا) "الرابط الديناميكي" لاستخدامه للرابط الحالي إذا كان سيتم فتحه باستخدام "روابط Firebase الديناميكية". بما أنّه يمكن ضبط نطاقات روابط ديناميكية متعدّدة لكل مشروع، يتيح هذا الحقل إمكانية اختيار نطاق واحد بشكلٍ صريح. إذا لم يتم تقديم أي نطاق، يتم استخدام النطاق الأول تلقائيًا. linkDomain سلسلة نطاق Firebase Hosting المخصّص الاختياري الذي سيتم استخدامه عند فتح الرابط من خلال تطبيق محدّد للأجهزة الجوّالة. يجب ضبط النطاق في Firebase Hosting وأن يكون مملوكًا للمشروع. لا يمكن أن يكون هذا النطاق نطاق 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. إذا لم تكن قد قبلت بعد بنود "الروابط الديناميكية" وأنشأت نطاقًا لها، يمكنك إجراء ذلك الآن.

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

      example.page.link

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

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

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

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

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

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

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

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

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

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

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

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

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

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