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

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