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

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

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

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

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

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

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

يجب تقديم مثيل ActionCodeSettings عند إرسال رسالة إلكترونية لإعادة ضبط كلمة المرور أو رسالة تحقق. ويمكن إنشاؤه باستخدام فئة ActionCodeSettings.Builder المرتبطة التي تحتوي على الطرق التالية:

الطريقة	الوصف
`setUrl(String url)`	تضبط الرابط (عنوان URL للحالة/المتابعة) معانٍ مختلفة في السياقات المختلفة: عند معالجة الرابط في أدوات إجراءات الويب، يكون هذا هو الرابط لصفحة في التطبيق في معلَمة طلب البحث `continueUrl`. عند معالجة الرابط في التطبيق مباشرةً، تكون هذه هي معلَمة طلب البحث `continueUrl` في الرابط لصفحة معيّنة في الرابط الديناميكي.
`setIOSBundleId(String iOSBundleId)`	لضبط معرّف حزمة iOS. سيؤدي هذا الإجراء إلى فتح الرابط في تطبيق iOS إذا كان مثبّتًا. يجب تسجيل تطبيق iOS في Console.
`setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion)`	لضبط اسم حزمة Android. سيؤدي هذا الإجراء إلى فتح الرابط في تطبيق Android في حال كان مثبّتًا. في حال ضبط installIfNot available على `true`، سيؤدّي ذلك إلى تحديد ما إذا كان عليك تثبيت تطبيق Android إذا كان التطبيق متوافقًا مع الجهاز ولم يسبق تثبيته. إذا تم تحديد الحدّ الأدنى للإصدار وتم تثبيت إصدار قديم من التطبيق، سيتم نقل المستخدم إلى "متجر Play" لترقية التطبيق. ويجب تسجيل تطبيق Android في Console.
`setHandleCodeInApp(boolean status)`	تحدّد هذه السمة ما إذا كان سيتم فتح رابط الإجراء الخاص بالرسالة الإلكترونية في تطبيق متوافق مع الأجهزة الجوّالة أم رابط ويب أولاً. وتكون القيمة التلقائية false. عند ضبط هذه السياسة على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android وسيفتح التطبيق إذا كان مثبّتًا. في الحالة الخاطئة، سيتم إرسال الرمز إلى تطبيق الويب المصغّر أولاً، ثم عند النقر على "متابعة"، ستتم إعادة التوجيه إلى التطبيق في حال تثبيته.
`setDynamicLinkDomain(String dynamicLinkDomain)`	تضبط نطاق الرابط الديناميكي (أو النطاق الفرعي) لاستخدامه مع الرابط الحالي إذا كان سيتم فتحه باستخدام روابط Firebase الديناميكية. وبما أنّه يمكن ضبط عدّة نطاقات روابط ديناميكية لكل مشروع، يوفّر هذا الحقل إمكانية اختيار نطاق بشكل صريح. وفي حال عدم تقديم أي نطاق، يتم استخدام النطاق الأول تلقائيًا.

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

Kotlin+KTX

val auth = Firebase.auth
val user = auth.currentUser!!

val url = "http://www.example.com/verify?uid=" + user.uid
val actionCodeSettings = ActionCodeSettings.newBuilder()
    .setUrl(url)
    .setIOSBundleId("com.example.ios")
    // The default for this is populated with the current android package name.
    .setAndroidPackageName("com.example.android", false, null)
    .build()

user.sendEmailVerification(actionCodeSettings)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d(TAG, "Email sent.")
        }
    }
MainActivity.kt

Java

FirebaseAuth auth = FirebaseAuth.getInstance();
FirebaseUser user = auth.getCurrentUser();

String url = "http://www.example.com/verify?uid=" + user.getUid();
ActionCodeSettings actionCodeSettings = ActionCodeSettings.newBuilder()
        .setUrl(url)
        .setIOSBundleId("com.example.ios")
        // The default for this is populated with the current android package name.
        .setAndroidPackageName("com.example.android", false, null)
        .build();

user.sendEmailVerification(actionCodeSettings)
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                if (task.isSuccessful()) {
                    Log.d(TAG, "Email sent.");
                }
            }
        });
MainActivity.java

إعداد روابط Firebase الديناميكية

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

تفعيل روابط Firebase الديناميكية:
1. في وحدة تحكُّم Firebase، افتح قسم الروابط الديناميكية.
2. إذا لم تكن قد قبلت أحكام "الروابط الديناميكية" بعد وأنشأت نطاق "روابط ديناميكية"، عليك إجراء ذلك الآن.
  
  إذا سبق لك إنشاء نطاق "روابط ديناميكية"، دوِّنه. يظهر نطاق الروابط الديناميكية عادةً على النحو التالي:
```
example.page.link
```
  ستحتاج إلى هذه القيمة عند ضبط تطبيق Apple أو Android لاعتراض الرابط الوارد.
تهيئة تطبيقات Android:
1. وإذا أردت التعامل مع هذه الروابط من تطبيق Android، يجب تحديد اسم حزمة Android في إعدادات المشروع على "وحدة تحكُّم Firebase". بالإضافة إلى ذلك، يلزم تقديم خوارزمية SHA-1 وSHA-256 لشهادة الطلب.
2. ستحتاج أيضًا إلى ضبط فلتر الأهداف لرابط الموضع المعيّن في ملف AndroidManifest.xml.
3. للمزيد من المعلومات عن هذا الموضوع، راجِع تلقّي تعليمات بشأن ميزة "روابط Android الديناميكية".
تهيئة تطبيقات iOS:
1. وإذا كنت تخطّط للتعامل مع هذه الروابط من تطبيق iOS، يجب تحديد معرّف حزمة iOS في إعدادات المشروع على "وحدة تحكُّم Firebase". بالإضافة إلى ذلك، يجب أيضًا تحديد معرّف App Store ومعرّف فريق مطوّر برامج Apple.
2. ستحتاج أيضًا إلى ضبط نطاق الرابط العام FDL كنطاق مرتبط في إمكانات التطبيق.
3. إذا كنت تخطّط لتوزيع تطبيقك على الإصدار 8 أو الإصدارات الأقدم من نظام التشغيل iOS، عليك ضبط معرّف حزمة iOS كمخطط مخصّص لعناوين URL الواردة.
4. للمزيد من المعلومات عن هذا الموضوع، راجِع تلقّي تعليمات بشأن الروابط الديناميكية لنظام التشغيل iOS.

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

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

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

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

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

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

يمكنك تحديد ما إذا كنت تريد التعامل مع رابط رمز الإجراء داخل تطبيق الأجهزة الجوّالة أولاً، بشرط أن يكون مثبتًا. مع تطبيقات Android، يمكنك أيضًا أن تحدّد من خلال القيمة المنطقية installIfNotAvailable أنّ التطبيق سيتم تثبيته إذا كان الجهاز يتيحه ولم يكن مثبّتًا. إذا تم النقر على الرابط من جهاز لا يتوافق مع تطبيق الأجهزة الجوّالة، سيتم فتحه من صفحة ويب بدلاً من ذلك. ويتم ذلك من خلال استدعاء setHandleCodeInApp(true) في كائن ActionCodeSettings.Builder. كما يجب أيضًا تحديد اسم حزمة Android أو معرّف حزمة iOS لتطبيق الأجهزة الجوّالة.

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

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