عبور از وضعیت در اقدامات ایمیل

هنگام ارسال اقدامات ایمیل برای بازنشانی رمز عبور یا تأیید ایمیل کاربر، می‌توانید وضعیت را از طریق URL ادامه دهید. این امکان را برای کاربر فراهم می کند تا پس از اتمام عمل به برنامه بازگردد. علاوه بر این، می‌توانید تعیین کنید که آیا پیوند اقدام ایمیل به‌جای یک صفحه وب، مستقیماً از یک برنامه تلفن همراه نصب می‌شود یا خیر.

این می تواند در سناریوهای رایج زیر بسیار مفید باشد:

  • کاربری که در حال حاضر وارد سیستم نشده است، ممکن است در تلاش برای دسترسی به محتوایی باشد که کاربر باید وارد سیستم شود. با این حال، کاربر ممکن است رمز عبور خود را فراموش کرده باشد و بنابراین جریان رمز عبور بازنشانی را آغاز کند. در پایان جریان، کاربر انتظار دارد به بخشی از برنامه که می‌خواست به آن دسترسی پیدا کند، برگردد.

  • یک برنامه فقط ممکن است دسترسی به حساب های تأیید شده را ارائه دهد. به عنوان مثال، یک برنامه خبرنامه ممکن است از کاربر بخواهد که ایمیل خود را قبل از اشتراک تأیید کند. کاربر جریان تأیید ایمیل را طی می کند و انتظار دارد برای تکمیل اشتراک خود به برنامه بازگردانده شود.

  • به طور کلی، هنگامی که یک کاربر بازنشانی رمز عبور یا جریان تأیید ایمیل را در یک برنامه اپل آغاز می کند، انتظار دارد جریان را در برنامه تکمیل کند. امکان انتقال حالت از طریق URL ادامه دهنده این امکان را فراهم می کند.

داشتن قابلیت انتقال حالت از طریق URL ادامه دهنده، ویژگی قدرتمندی است که Firebase Auth ارائه می کند و می تواند تجربه کاربر را به میزان قابل توجهی افزایش دهد.

عبور URL وضعیت/ادامه در اقدامات ایمیل

برای ارسال ایمن URL ادامه، دامنه برای URL باید در کنسول Firebase در لیست مجاز قرار گیرد. این کار در بخش Authentication با افزودن این دامنه به لیست دامنه های مجاز در زبانه روش ورود به سیستم ، در صورتی که قبلاً وجود ندارد، انجام می شود.

هنگام ارسال ایمیل بازنشانی رمز عبور یا ایمیل تأیید، باید یک نمونه ActionCodeSettings ارائه شود. این رابط پارامترهای زیر را می گیرد:

پارامتر تایپ کنید توضیحات
url رشته

پیوند (وضعیت/ادامه URL) را تنظیم می کند که در زمینه های مختلف معانی مختلفی دارد:

  • هنگامی که پیوند در ویجت‌های عملیات وب مدیریت می‌شود، این پیوند عمیق در پارامتر پرس و جو continueUrl است.
  • هنگامی که پیوند مستقیماً در برنامه مدیریت می شود، این پارامتر query continueUrl در پیوند عمیق پیوند پویا است.
iOSBundleId رشته شناسه بسته را تنظیم می کند. در صورت نصب، سعی می شود پیوند را در یک برنامه اپل باز کند. برنامه باید در کنسول ثبت شود. اگر شناسه بسته ارائه نشده باشد، مقدار این فیلد روی شناسه بسته نرم افزاری اصلی برنامه تنظیم می شود.
androidPackageName رشته نام بسته اندروید را تنظیم می کند. با این کار سعی می شود در صورت نصب لینک در یک برنامه اندرویدی باز شود.
androidInstallApp بوول مشخص می کند که اگر دستگاه از برنامه Android پشتیبانی می کند و برنامه قبلاً نصب نشده است، برنامه Android را نصب کنید یا خیر. اگر این فیلد بدون packageName ارائه شود، خطایی ایجاد می‌شود که توضیح می‌دهد packageName باید همراه با این فیلد ارائه شود.
androidMinimumVersion رشته حداقل نسخه برنامه ای که در این جریان پشتیبانی می شود. اگر minimalVersion مشخص شده باشد و نسخه قدیمی‌تری از برنامه نصب شده باشد، کاربر برای ارتقای برنامه به فروشگاه Play منتقل می‌شود. برنامه اندروید باید در کنسول ثبت شود.
handleCodeInApp بوول آیا پیوند اقدام ایمیل ابتدا در یک برنامه تلفن همراه باز می شود یا یک پیوند وب. پیش فرض نادرست است. وقتی روی true تنظیم شود، پیوند کد اقدام به عنوان پیوند جهانی یا پیوند برنامه Android ارسال می‌شود و در صورت نصب توسط برنامه باز می‌شود. در صورت نادرست، کد ابتدا به ویجت وب ارسال می شود و سپس در صورت نصب به برنامه ادامه می دهد.
dynamicLinkDomain رشته دامنه پیوند پویا (یا زیر دامنه) را برای استفاده برای پیوند فعلی تنظیم می کند، اگر قرار است با استفاده از پیوندهای دینامیک 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 Auth هنگام ارسال پیوندی که قرار است در یک برنامه تلفن همراه باز شود، از Firebase Dynamic Links استفاده می کند. برای استفاده از این ویژگی، پیوندهای پویا باید در کنسول Firebase پیکربندی شوند.

  1. فعال کردن Firebase Dynamic Links:

    1. در کنسول Firebase، بخش Dynamic Links را باز کنید.

    2. اگر هنوز شرایط Dynamic Links را نپذیرفته اید و دامنه Dynamic Links ایجاد نکرده اید، اکنون این کار را انجام دهید.

    3. اگر قبلاً یک دامنه پیوندهای پویا ایجاد کرده‌اید، به آن توجه داشته باشید. یک دامنه Dynamic Links معمولاً مانند مثال زیر است: 

      example.page.link

    4. هنگامی که برنامه Apple یا Android خود را برای رهگیری پیوند ورودی پیکربندی می کنید، به این مقدار نیاز خواهید داشت.

  2. پیکربندی برنامه های اندروید:

    1. اگر قصد دارید این پیوندها را از برنامه Android خود مدیریت کنید، نام بسته Android باید در تنظیمات پروژه Firebase Console مشخص شود. علاوه بر این، SHA-1 و SHA-256 گواهی درخواست باید ارائه شود.
    2. همچنین باید فیلتر هدف را برای پیوند عمیق موجود در فایل AndroidManifest.xml خود پیکربندی کنید.
    3. برای اطلاعات بیشتر در این مورد، به دستورالعمل‌های دریافت پیوندهای پویا اندروید مراجعه کنید.

  3. پیکربندی برنامه های اپل:

    1. اگر قصد دارید این پیوندها را از برنامه خود مدیریت کنید، شناسه بسته باید در تنظیمات پروژه Firebase Console مشخص شود. علاوه بر این، شناسه App Store و Apple Developer Team ID نیز باید مشخص شود.
    2. همچنین باید دامنه پیوند جهانی FDL را به عنوان یک دامنه مرتبط در قابلیت های برنامه خود پیکربندی کنید.
    3. اگر قصد دارید برنامه خود را در نسخه های iOS 8 و پایین تر توزیع کنید، باید ID بسته خود را به عنوان یک طرح سفارشی برای URL های ورودی تنظیم کنید.
    4. برای اطلاعات بیشتر در این مورد، به دستورالعمل‌های دریافت پیوندهای پویا پلتفرم‌های اپل مراجعه کنید.

مدیریت اقدامات ایمیل در یک برنامه وب

می‌توانید تعیین کنید که آیا می‌خواهید ابتدا پیوند کد عمل را از یک برنامه وب مدیریت کنید و سپس پس از تکمیل موفقیت‌آمیز به صفحه وب یا برنامه تلفن همراه دیگر هدایت شوید، مشروط بر اینکه برنامه تلفن همراه در دسترس باشد. این کار با تنظیم handleCodeInApp روی false در شی ActionCodeSettings انجام می شود. در حالی که به شناسه بسته یا نام بسته Android نیازی نیست، ارائه آنها به کاربر اجازه می‌دهد پس از تکمیل کد اقدام ایمیل، به برنامه مشخص‌شده هدایت شود.

URL وب مورد استفاده در اینجا، همانی است که در بخش الگوهای اقدام ایمیل پیکربندی شده است. یک پیش فرض برای همه پروژه ها ارائه شده است. برای کسب اطلاعات بیشتر در مورد نحوه سفارشی کردن کنترل کننده اقدام ایمیل، به سفارشی کردن کنترل کننده های ایمیل مراجعه کنید.

در این حالت، پیوند درون پارامتر query continueURL یک پیوند FDL خواهد بود که بارگذاری آن URL مشخص شده در شی ActionCodeSettings است. در حالی که می‌توانید پیوند ورودی از برنامه خود را بدون وابستگی اضافی رهگیری و مدیریت کنید، توصیه می‌کنیم از کتابخانه مشتری FDL برای تجزیه پیوند عمیق برای شما استفاده کنید.

هنگام مدیریت اقدامات ایمیل مانند تأیید ایمیل، کد اقدام از پارامتر query oobCode باید از پیوند عمیق تجزیه شود و سپس از طریق applyActionCode اعمال شود تا تغییر اعمال شود، یعنی ایمیل تأیید شود.

مدیریت اقدامات ایمیل در یک برنامه تلفن همراه

می‌توانید تعیین کنید که آیا می‌خواهید ابتدا پیوند کد اقدام را در برنامه تلفن همراه خود مدیریت کنید، به شرطی که نصب باشد. در برنامه‌های اندروید، شما همچنین می‌توانید از طریق androidInstallApp تعیین کنید که اگر دستگاه از آن پشتیبانی می‌کند و قبلاً نصب نشده است، نصب شود. اگر روی پیوند از دستگاهی که از برنامه تلفن همراه پشتیبانی نمی کند کلیک شود، به جای آن از یک صفحه وب باز می شود. این کار با تنظیم handleCodeInApp روی true در شیء ActionCodeSettings انجام می شود. نام بسته Android برنامه تلفن همراه یا شناسه بسته نیز باید مشخص شود. URL وب بازگشتی که در اینجا استفاده می‌شود، زمانی که هیچ برنامه تلفن همراهی در دسترس نیست، همانی است که در بخش الگوهای اقدام ایمیل پیکربندی شده است. یک پیش فرض برای همه پروژه ها ارائه شده است. برای کسب اطلاعات بیشتر در مورد نحوه سفارشی کردن کنترل کننده اقدام ایمیل، به سفارشی کردن کنترل کننده های ایمیل مراجعه کنید.

در این حالت، پیوند برنامه تلفن همراه ارسال شده به کاربر، یک پیوند FDL خواهد بود که بارگذاری آن URL کد اقدام است که در کنسول پیکربندی شده است، با پارامترهای جستجو oobCode ، mode ، apiKey و continueUrl . دومی URL اصلی مشخص شده در شی ActionCodeSettings خواهد بود. در حالی که می‌توانید پیوند ورودی از برنامه خود را بدون وابستگی اضافی رهگیری و مدیریت کنید، توصیه می‌کنیم از کتابخانه مشتری FDL برای تجزیه پیوند عمیق برای شما استفاده کنید. کد اقدام را می توان مستقیماً از یک برنامه تلفن همراه مانند نحوه استفاده از جریان وب شرح داده شده در بخش سفارشی سازی کنترل کننده های ایمیل اعمال کرد.

هنگام مدیریت اقدامات ایمیل مانند تأیید ایمیل، کد اقدام از پارامتر query oobCode باید از پیوند عمیق تجزیه شود و سپس از طریق applyActionCode اعمال شود تا تغییر اعمال شود، یعنی ایمیل تأیید شود.