يمكنك تمرير الحالة عبر عنوان URL للمتابعة عند إرسال إجراءات البريد الإلكتروني لإعادة ضبط كلمة المرور أو عند التحقّق من البريد الإلكتروني للمستخدم. يوفر هذا للمستخدم إمكانية العودة إلى التطبيق بعد اكتمال الإجراء. بالإضافة إلى ذلك، يمكنك تحديد ما إذا كنت تريد معالجة رابط إجراء البريد الإلكتروني مباشرةً من تطبيق للأجهزة الجوّالة عند تثبيته بدلاً من صفحة ويب.
قد يكون هذا مفيدًا للغاية في السيناريوهات الشائعة التالية:
قد يحاول مستخدم، لم يسجّل الدخول حاليًا، الوصول إلى محتوى يتطلب تسجيل دخوله. ومع ذلك، ربما نسي المستخدم كلمة المرور الخاصة به، وبالتالي يؤدي إلى تشغيل مسار إعادة تعيين كلمة المرور. في نهاية التدفق، يتوقع المستخدم العودة إلى قسم التطبيق الذي كان يحاول الوصول إليه.
لا يجوز أن يوفّر أحد التطبيقات سوى إمكانية الوصول إلى الحسابات التي تم التحقّق منها. على سبيل المثال، قد يطلب تطبيق النشرة الإخبارية من المستخدم إثبات ملكية بريده الإلكتروني قبل الاشتراك. يمر المستخدم بخطوات التحقق من البريد الإلكتروني ويتوقع إعادته إلى التطبيق لإكمال اشتراكه.
بشكل عام، عندما يبدأ المستخدم عملية إعادة ضبط كلمة المرور أو إثبات ملكية عنوان البريد الإلكتروني على تطبيق Apple، يتوقّع إكمال عملية الخطوات داخل التطبيق، ومن خلال إمكانية تمرير الحالة من خلال عنوان URL للمتابعة، يصبح هذا ممكنًا.
إنّ إمكانية ضبط الحالة عبر عنوان URL للمتابعة هي ميزة فعّالة توفّرها مصادقة Firebase ويمكنها تحسين تجربة المستخدم بشكل كبير.
حالة التمرير/متابعة عنوان URL في إجراءات البريد الإلكتروني
لتمرير عنوان URL للمتابعة بشكل آمن، يجب أن يكون نطاق عنوان URL مُدرَجًا في القائمة المسموح بها في وحدة تحكُّم Firebase. ويتم إجراء ذلك في قسم المصادقة من خلال إضافة هذا النطاق إلى قائمة النطاقات المفوَّضة ضمن علامة التبويب طريقة تسجيل الدخول إذا لم يكن هذا النطاق مُدرجًا.
يجب تقديم مثيل ActionCodeSettings
عند إرسال
رسالة إلكترونية لإعادة ضبط كلمة المرور أو رسالة تأكيد. تستخدم هذه الواجهة المعلمات التالية:
المَعلمة | Type | الوصف |
---|---|---|
url |
String | تضبط الرابط (عنوان URL للحالة/المتابعة) معانٍ مختلفة في السياقات المختلفة:
|
iOSBundleId |
String | لضبط معرّف الحزمة. سيؤدي هذا الإجراء إلى فتح الرابط في تطبيق Apple إذا كان مثبّتًا. يجب تسجيل التطبيق في Console. إذا لم يتم تقديم معرِّف حزمة، يتم ضبط قيمة هذا الحقل على معرِّف الحزمة للحزمة الرئيسية للتطبيق. |
androidPackageName |
String | لضبط اسم حزمة Android. سيؤدي هذا الإجراء إلى فتح الرابط في تطبيق Android في حال كان مثبّتًا. |
androidInstallApp |
قيمة منطقية (Bool) | تحدِّد هذه السياسة ما إذا كان سيتم تثبيت تطبيق Android إذا كان الجهاز متوافقًا مع هذا التطبيق ولم يكن التطبيق مثبَّتًا من قبل. إذا تم توفير هذا الحقل بدون packageName، يتم عرض خطأ يوضّح أنّه يجب توفير packageName مع هذا الحقل. |
androidMinimumVersion |
String | تمثّل هذه السمة الحد الأدنى من إصدار التطبيق المتوافق في هذا المسار. في حال تحديد الحدّ الأدنى للإصدار وتثبيت إصدار قديم من التطبيق، سيتم نقل المستخدم إلى "متجر Play" لترقية التطبيق. ويجب تسجيل تطبيق Android في Console. |
handleCodeInApp |
قيمة منطقية (Bool) | تحدّد هذه السمة ما إذا كان سيتم فتح رابط الإجراء الخاص بالرسالة الإلكترونية في تطبيق متوافق مع الأجهزة الجوّالة أم رابط ويب أولاً. وتكون القيمة التلقائية false. عند ضبط هذه السياسة على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android وسيفتح التطبيق إذا كان مثبّتًا. في الحالة الخاطئة، سيتم إرسال الرمز إلى تطبيق الويب المصغّر أولاً، ثم عند النقر على "متابعة"، ستتم إعادة التوجيه إلى التطبيق في حال تثبيته. |
dynamicLinkDomain |
String | تضبط نطاق الرابط الديناميكي (أو النطاق الفرعي) لاستخدامه مع الرابط الحالي إذا كان سيتم فتحه باستخدام روابط Firebase الديناميكية. وبما أنّه يمكن ضبط عدّة نطاقات روابط ديناميكية لكل مشروع، يوفّر هذا الحقل إمكانية اختيار نطاق بشكل صريح. وفي حال عدم تقديم أي نطاق، يتم استخدام النطاق الأول تلقائيًا. |
يوضّح المثال التالي كيفية إرسال رابط لإثبات ملكية عنوان البريد الإلكتروني ليتم فتحه أولاً في تطبيق للأجهزة الجوّالة كرابط ديناميكي في 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 الديناميكية
تستخدم مصادقة Firebase روابط Firebase الديناميكية عند إرسال رابط من المفترض أن يتم فتحه في تطبيق للأجهزة الجوّالة. يجب إعداد الروابط الديناميكية في "وحدة تحكُّم Firebase" لاستخدام هذه الميزة.
تفعيل روابط Firebase الديناميكية:
في "وحدة تحكُّم Firebase"، افتح قسم الروابط الديناميكية.
إذا لم تكن قد قبلت بنود "الروابط الديناميكية" بعد وأنشأت نطاق "روابط ديناميكية"، افعل ذلك الآن.
إذا سبق لك إنشاء نطاق "روابط ديناميكية"، دوِّنه. يظهر نطاق الروابط الديناميكية عادةً على النحو التالي:
example.page.link
ستحتاج إلى هذه القيمة عند إعداد تطبيق Android أو Apple لاعتراض الرابط الوارد.
تهيئة تطبيقات Android:
- وإذا أردت التعامل مع هذه الروابط من تطبيق Android، يجب تحديد اسم حزمة Android في إعدادات المشروع على "وحدة تحكُّم Firebase". بالإضافة إلى ذلك، يلزم تقديم خوارزمية SHA-1 وSHA-256 لشهادة الطلب.
- ستحتاج أيضًا إلى ضبط فلتر الأهداف لرابط الموضع المعيّن في ملف AndroidManifest.xml.
- للمزيد من المعلومات عن هذا الموضوع، راجِع تلقّي تعليمات بشأن ميزة "روابط Android الديناميكية".
تكوين تطبيقات Apple:
- إذا كنت تخطط للتعامل مع هذه الروابط من تطبيقك، يجب تحديد معرّف الحزمة في إعدادات المشروع في "وحدة تحكُّم Firebase". بالإضافة إلى ذلك، يجب أيضًا تحديد معرّف App Store ومعرّف فريق مطوّر برامج Apple.
- ستحتاج أيضًا إلى ضبط نطاق الرابط العام FDL كنطاق مرتبط في إمكانات التطبيق.
- إذا كنت تخطِّط لتوزيع تطبيقك على الإصدار 8 أو الإصدارات الأقدم من نظام التشغيل iOS، عليك ضبط معرّف الحزمة كمخطط مخصّص لعناوين URL الواردة.
- للمزيد من المعلومات عن هذا الموضوع، يمكنك الرجوع إلى تعليمات تلقّي الروابط الديناميكية من منصات Apple.
التعامل مع إجراءات البريد الإلكتروني في تطبيق ويب
يمكنك تحديد ما إذا كنت تريد أولاً معالجة رابط رمز الإجراء من تطبيق ويب، ثم إعادة التوجيه إلى صفحة ويب أو تطبيق للأجهزة الجوّالة آخر بعد إكمال العملية بنجاح، بشرط أن يكون التطبيق المتوافق مع الأجهزة الجوّالة متاحًا.
ويتم ذلك من خلال ضبط handleCodeInApp
على false
في كائن ActionCodeSettings
. علمًا أنّ معرّف الحزمة أو اسم حزمة Android غير مطلوبَين، إلا أنّ توفيرهما سيسمح للمستخدم بإعادة التوجيه إلى التطبيق المحدّد عند إكمال رمز إجراء البريد الإلكتروني.
وعنوان URL المستخدَم هنا هو العنوان الذي تم ضبطه في قسم "نماذج الإجراءات عبر البريد الإلكتروني". يتم توفير نموذج تلقائي لجميع المشاريع. يمكنك الاطّلاع على تخصيص معالِجات البريد الإلكتروني لمعرفة المزيد من المعلومات عن كيفية تخصيص معالِجات إجراء البريد الإلكتروني.
في هذه الحالة، سيكون الرابط ضمن معلَمة طلب البحث continueURL
هو رابط FDL تكون حمولةته هي URL
المحددة في الكائن ActionCodeSettings
. على الرغم من أنّه يمكنك اعتراض الرابط الوارد من تطبيقك والتعامل معه بدون أي تبعية إضافية، ننصحك باستخدام مكتبة برامج FDL لتحليل الرابط لصفحة في التطبيق.
عند التعامل مع إجراءات البريد الإلكتروني، مثل إثبات ملكية عنوان البريد الإلكتروني، يجب تحليل رمز الإجراء من معلَمة طلب البحث "oobCode
" من الرابط لصفحة في التطبيق، ثم تطبيقه من خلال "applyActionCode
" لكي يتم تطبيق التغيير، أي البريد الإلكتروني الذي يتم التحقّق منه.
التعامل مع إجراءات البريد الإلكتروني في تطبيق للأجهزة الجوّالة
يمكنك تحديد ما إذا كنت تريد التعامل مع رابط رمز الإجراء داخل تطبيق الأجهزة الجوّالة أولاً، بشرط أن يكون مثبتًا. وفي تطبيقات Android،
يمكنك أيضًا أن تحدّد عبر androidInstallApp
أنّ
التطبيق سيتم تثبيته إذا كان الجهاز يتيحه ولم يكن
مثبّتًا من قبل.
إذا تم النقر على الرابط من جهاز لا يتوافق مع تطبيق الأجهزة الجوّالة، سيتم فتحه من صفحة ويب بدلاً من ذلك.
ويتم ذلك من خلال ضبط handleCodeInApp
على true
في كائن ActionCodeSettings
. كما يجب أيضًا تحديد اسم حزمة Android أو معرّف الحزمة لتطبيق الأجهزة الجوّالة.وعنوان URL الاحتياطي للويب المستخدَم هنا، في حال عدم توفّر أي تطبيق للأجهزة الجوّالة، هو العنوان الذي تم إعداده في قسم نماذج إجراءات البريد الإلكتروني. يتم توفير واحد افتراضي
لجميع المشروعات. يمكنك الاطّلاع على تخصيص معالِجات البريد الإلكتروني لمعرفة المزيد من المعلومات عن كيفية تخصيص معالِجات إجراء البريد الإلكتروني.
في هذه الحالة، سيكون رابط التطبيق المتوافق مع الأجهزة الجوّالة الذي يتم إرساله إلى المستخدم هو رابط FDL
وتكون حمولته هي عنوان URL لرمز الإجراء، والذي تم إعداده في وحدة التحكّم، مع مَعلمات طلب البحث oobCode
وmode
وapiKey
وcontinueUrl
. وسيكون الاسم الثاني هو URL
الأصلي المحدّد في كائن ActionCodeSettings
. على الرغم من أنّه يمكنك اعتراض الرابط الوارد من تطبيقك والتعامل معه بدون أي تبعية إضافية، ننصحك
باستخدام مكتبة برامج FDL لتحليل الرابط المؤدي لصفحة معيّنة من أجلك. يمكن تطبيق رمز الإجراء مباشرةً من تطبيق للأجهزة الجوّالة بالطريقة نفسها التي يتم بها التعامل معه من خلال مسار الويب الموضّح في قسم تخصيص معالِجات البريد الإلكتروني.
عند التعامل مع إجراءات البريد الإلكتروني، مثل إثبات ملكية عنوان البريد الإلكتروني، يجب تحليل رمز الإجراء من معلَمة طلب البحث "oobCode
" من الرابط لصفحة في التطبيق، ثم تطبيقه من خلال "applyActionCode
" لكي يتم تطبيق التغيير، أي البريد الإلكتروني الذي يتم التحقّق منه.