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

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

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

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

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

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

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

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

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

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

الطريقة الوصف
setUrl(String url)

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

  • عند معالجة الرابط في التطبيقات المصغّرة لإجراءات الويب، يكون هذا هو الرابط العميق في مَعلمة طلب البحث continueUrl.
  • عند معالجة الرابط في التطبيق مباشرةً، تكون هذه هي مَعلمة طلب البحث continueUrl في الرابط لصفحة في التطبيق "للرابط الديناميكي".
setIOSBundleId(String iOSBundleId) لضبط معرِّف حزمة iOS سيؤدي ذلك إلى محاولة فتح الرابط في تطبيق iOS إذا كان مثبّتًا. يجب تسجيل تطبيق iOS في Play Console.
setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion) تُستخدَم لضبط اسم حزمة Android. سيؤدي ذلك إلى محاولة فتح الرابط في تطبيق Android إذا كان مثبّتًا. إذا تم ضبط installIfNotAvailable على true، يتم تحديد ما إذا كان سيتم تثبيت تطبيق Android إذا كان الجهاز متوافقًا معه ولم يكن التطبيق مثبّتًا من قبل. في حال تحديد minimumVersion وتم تثبيت إصدار قديم من التطبيق، سيتم توجيه المستخدم إلى "متجر Play" لترقية التطبيق. يجب تسجيل تطبيق Android في Play 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

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 Auth روابط Firebase الديناميكية عند إرسال رابط مخصّص للفتح في تطبيق متوافق مع الأجهزة الجوّالة. لاستخدام هذه الميزة، يجب ضبط "الروابط الديناميكية" في وحدة تحكّم Firebase.

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

    1. في وحدة تحكّم Firebase، افتح قسم Dynamic Links.

    2. إذا لم يسبق لك قبول بنود Dynamic Links وإنشاء نطاق Dynamic Links ، يُرجى إجراء ذلك الآن.

      إذا سبق لك إنشاء نطاق Dynamic Links، عليك تدوينه. يظهر نطاق Dynamic Links عادةً بالشكل التالي:

      example.page.link

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

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

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

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

    1. إذا كنت تخطّط للتعامل مع هذه الروابط من تطبيق iOS، يجب تحديد معرّف حِزمة iOS في إعدادات مشروع Firebase Console. بالإضافة إلى ذلك، يجب أيضًا تحديد رقم تعريف 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 لتحليل الرابط لصفحة في التطبيق بدلاً من ذلك. يمكن تطبيق رمز الإجراء مباشرةً من تطبيق متوافق مع الأجهزة الجوّالة بطريقة مشابهة لطريقة معالجته من خلال مسار الويب الموضّح في القسم تخصيص معالجات البريد الإلكتروني.

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