העברת מצב בפעולות באימייל

כששולחים פעולות באימייל לאיפוס סיסמה או לאימות כתובת אימייל של משתמש, אפשר להעביר את הסטטוס באמצעות כתובת URL להמשך. האפשרות הזו מאפשרת למשתמש לחזור לאפליקציה אחרי השלמת הפעולה. בנוסף, אתם יכולים לציין אם לטפל בקישור לפעולה באימייל ישירות מאפליקציה לנייד כשהיא מותקנת, במקום מדף אינטרנט.

האפשרות הזו יכולה להיות שימושית מאוד בתרחישים הנפוצים הבאים:

  • יכול להיות שמשתמש שלא מחובר כרגע מנסה לגשת לתוכן שנדרשת גישה אליו. עם זאת, יכול להיות שהמשתמש שכח את הסיסמה שלו ולכן יפעיל את תהליך איפוס הסיסמה. בסוף התהליך, המשתמש מצפה לחזור לקטע באפליקציה שאליו הוא ניסה לגשת.

  • אפליקציה יכולה להציע גישה רק לחשבונות מאומתים. לדוגמה, אפליקציה לניוזלטר עשויה לדרוש מהמשתמש לאמת את כתובת האימייל שלו לפני שהוא נרשם. המשתמש יעבור את תהליך אימות כתובת האימייל ויצפה לחזור לאפליקציה כדי להשלים את המינוי.

  • באופן כללי, כשמשתמש מתחיל תהליך לאיפוס סיסמה או לאימות כתובת אימייל באפליקציית Apple, הוא מצפה להשלים את התהליך בתוך האפליקציה. האפשרות להעביר את הסטטוס באמצעות כתובת URL להמשך מאפשרת זאת.

היכולת להעביר מצב באמצעות כתובת URL להמשך היא תכונה עוצמתית ש-Firebase Auth מספקת, והיא יכולה לשפר משמעותית את חוויית המשתמש.

העברת מצב או כתובת URL להמשך בפעולות באימייל

כדי להעביר כתובת URL להמשך בצורה מאובטחת, צריך להוסיף את הדומיין של כתובת ה-URL לרשימת ההיתרים במסוף Firebase. כדי לעשות זאת, מוסיפים את הדומיין לרשימת הדומיינים המורשים בקטע אימות בכרטיסייה שיטת הכניסה, אם הוא עדיין לא מופיע שם.

צריך לספק מופע של ActionCodeSettings כששולחים אימייל לאיפוס סיסמה או הודעת אימות. הממשק הזה מקבל את הפרמטרים הבאים:

פרמטר סוג תיאור
url מחרוזת

הפונקציה מגדירה את הקישור (כתובת URL של מצב/כתובת URL להמשך) שיש לו משמעויות שונות בהקשרים שונים:

  • כשמטפלים בקישור בווידג'טים של פעולות באתר, זהו קישור העומק בפרמטר השאילתה continueUrl.
  • אם הקישור מטופל ישירות באפליקציה, זהו פרמטר השאילתה continueUrl בקישור העומק של הקישור הדינמי.
iOSBundleId מחרוזת מגדירה את מזהה החבילה. המערכת תנסה לפתוח את הקישור באפליקציה של אפל אם היא מותקנת. האפליקציה צריכה להיות רשומה ב-Console. אם לא צוין מזהה חבילה, הערך של השדה הזה מוגדר כמזהה החבילה של החבילה הראשית של האפליקציה.
androidPackageName מחרוזת הגדרת שם החבילה ב-Android. המערכת תנסה לפתוח את הקישור באפליקציית Android אם היא מותקנת.
androidInstallApp bool המדיניות הזו מציינת אם להתקין את אפליקציית Android אם המכשיר תומך בה והיא עדיין לא מותקנת. אם השדה הזה מסופק ללא packageName, מוצגת שגיאה שמסבירה שחובה לספק את packageName יחד עם השדה הזה.
androidMinimumVersion מחרוזת הגרסה המינימלית של האפליקציה שנתמכת בתהליך הזה. אם מציינים את הערך minimumVersion, ומותקנת גרסה ישנה יותר של האפליקציה, המשתמש מועבר לחנות Play כדי לשדרג את האפליקציה. צריך לרשום את אפליקציית Android ב-Console.
handleCodeInApp bool האם הקישור לפעולה באימייל ייפתח קודם באפליקציה לנייד או בקישור לאינטרנט. ברירת המחדל היא false. אם המדיניות מוגדרת כ-True, הקישור עם קוד הפעולה יישלח כקישור אוניברסלי או כקישור לאפליקציית Android, והאפליקציה תפתח אותו אם היא מותקנת. במקרה של false, הקוד יישלח קודם לווידג'ט האינטרנט ואז, בלחיצה על 'המשך', המשתמש יופנה לאפליקציה אם היא מותקנת.
dynamicLinkDomain מחרוזת (הוצא משימוש, צריך להשתמש ב-`linkDomain`) מגדיר את הדומיין (או תת-הדומיין) של הקישור הדינמי שבו יש להשתמש עבור הקישור הנוכחי אם הוא אמור להיפתח באמצעות קישורים דינמיים ב-Firebase. אפשר להגדיר כמה דומיינים של קישורים דינמיים לכל פרויקט, ולכן השדה הזה מאפשר לבחור אחד מהם באופן מפורש. אם לא מציינים דומיין, המערכת משתמשת בדומיין הראשון כברירת מחדל. linkDomain מחרוזת דומיין אירוח מותאם אישית ב-Firebase שאפשר להשתמש בו כשפותחים את הקישור דרך אפליקציה ספציפית לנייד. הדומיין צריך להיות מוגדר ב-Firebase Hosting ולהיות בבעלות הפרויקט. הדומיין לא יכול להיות דומיין ברירת מחדל של Hosting‏ (`web.app` או `firebaseapp.com`). ההגדרה הזו מחליפה את ההגדרה `dynamicLinkDomain` שיצאה משימוש.

בדוגמה הבאה מוצג קישור לאימות כתובת אימייל שייפתח קודם באפליקציה לנייד כקישור דינמי ב-Firebase, באמצעות הדומיין המותאם אישית של הקישור הדינמי example.page.link (אפליקציית iOS‏ com.example.ios או אפליקציית Android‏ com.example.android שבהן האפליקציה תותקן אם היא עדיין לא מותקנת והגרסה המינימלית היא 12). קישור העומק יכיל את מטען הייעודי (payload) של כתובת ה-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 כששולחים קישור שנועד להיפתח באפליקציה לנייד. כדי להשתמש בתכונה הזו, צריך להגדיר קישורים דינמיים במסוף Firebase.

  1. מפעילים קישורים דינמיים ב-Firebase:

    1. במסוף Firebase, פותחים את הקטע קישורים דינמיים.

    2. אם עדיין לא אישרתם את התנאים וההגבלות של Dynamic Links ויצרתם דומיין Dynamic Links, עליכם לעשות זאת עכשיו.

    3. אם כבר יצרתם דומיין של Dynamic Links, כדאי לרשום אותו. דוגמה לשם דומיין של Dynamic Links: 

      example.page.link

    4. תצטרכו את הערך הזה כשאתם מגדירים את האפליקציה שלכם ל-Apple או ל-Android כדי ליירט את הקישור הנכנס.

  2. הגדרת אפליקציות ל-Android:

    1. אם אתם מתכננים לטפל בקישורים האלה מאפליקציית Android שלכם, צריך לציין את שם החבילה ל-Android בהגדרות הפרויקט ב-Firebase Console. בנוסף, צריך לספק את SHA-1 ו-SHA-256 של אישור האפליקציה.
    2. תצטרכו גם להגדיר את מסנן ה-Intent לקישור העומק בקובץ AndroidManifest.xml.
    3. מידע נוסף זמין במאמר בנושא קבלת הוראות לקישורים דינמיים ב-Android.

  3. הגדרת אפליקציות של Apple:

    1. אם אתם מתכננים לטפל בקישורים האלה מהאפליקציה שלכם, צריך לציין את מזהה החבילה בהגדרות הפרויקט במסוף Firebase. בנוסף, צריך לציין את המזהה של האפליקציה ב-App Store ואת מזהה הצוות של מפתחי אפל.
    2. בנוסף, תצטרכו להגדיר את הדומיין של הקישור האוניברסלי של FDL כ-Associated Domain ביכולות האפליקציה.
    3. אם אתם מתכננים להפיץ את האפליקציה שלכם לגרסאות iOS 8 ומטה, תצטרכו להגדיר את מזהה החבילה כסכימה בהתאמה אישית לכתובות URL נכנסות.
    4. מידע נוסף זמין במאמר בנושא קבלת הוראות לקישורים דינמיים בפלטפורמות של אפל.

טיפול בפעולות באימייל באפליקציית אינטרנט

אתם יכולים לציין אם אתם רוצים לטפל בקישור של קוד הפעולה קודם באפליקציית אינטרנט ואז להפנות מחדש לדף אינטרנט אחר או לאפליקציה לנייד אחרי השלמה מוצלחת, בתנאי שהאפליקציה לנייד זמינה. כדי לעשות את זה, צריך להגדיר את handleCodeInApp ל-false באובייקט ActionCodeSettings. לא חובה לציין מזהה חבילה או שם חבילה ב-Android, אבל אם תציינו אותם, המשתמש יוכל לחזור לאפליקציה שצוינה אחרי שישלים את הפעולה בקוד האימות שקיבל באימייל.

כתובת ה-URL של האתר שבה נעשה שימוש כאן היא זו שהוגדרה בקטע של תבניות פעולות באימייל. מוקצה לכל הפרויקטים אחד כברירת מחדל. מידע נוסף על התאמה אישית של handler של פעולות באימייל זמין במאמר בנושא התאמה אישית של handlers של אימיילים.

במקרה כזה, הקישור בפרמטר השאילתה continueURL יהיה קישור FDL שהמטען הייעודי שלו הוא URL שצוין באובייקט ActionCodeSettings. אמנם אפשר ליירט את הקישור הנכנס מהאפליקציה ולטפל בו בלי תלות נוספת, אבל מומלץ להשתמש בספריית הלקוח של FDL כדי לנתח את קישור העומק.

כשמטפלים בפעולות שקשורות לאימייל, כמו אימות כתובת אימייל, צריך לנתח את קוד הפעולה מפרמטר השאילתה oobCode של קישור העומק, ואז להחיל אותו באמצעות applyActionCode כדי שהשינוי ייכנס לתוקף, כלומר כדי שהאימייל יאומת.

טיפול בפעולות שקשורות לאימייל באפליקציה לנייד

אתם יכולים לציין אם אתם רוצים לטפל קודם בקישור עם קוד הפעולה באפליקציה לנייד, בתנאי שהיא מותקנת. באמצעות אפליקציות ל-Android, אפשר גם לציין באמצעות androidInstallApp שהאפליקציה תותקן אם המכשיר תומך בה והיא עדיין לא מותקנת. אם לוחצים על הקישור ממכשיר שלא תומך באפליקציה לנייד, הקישור ייפתח מדף אינטרנט במקום זאת. כדי לעשות את זה, צריך להגדיר את handleCodeInApp ל-true באובייקט ActionCodeSettings. צריך גם לציין את שם חבילת Android או את מזהה החבילה של האפליקציה לנייד.כתובת ה-URL לגיבוי שמשמשת כאן, כשאין אפליקציה לנייד, היא זו שהוגדרה בקטע של תבניות פעולות באימייל. מוקצה אחד כברירת מחדל לכל הפרויקטים. מידע נוסף על התאמה אישית של handler של פעולות באימייל זמין במאמר בנושא התאמה אישית של handlers של אימיילים.

במקרה הזה, הקישור לאפליקציה לנייד שנשלח למשתמש יהיה קישור FDL שהמטען הייעודי שלו הוא כתובת ה-URL של קוד הפעולה, שהוגדרה במסוף, עם פרמטרי השאילתה oobCode, mode, apiKey ו-continueUrl. האחרון יהיה URL המקורי שצוין באובייקט ActionCodeSettings. אפשר ליירט את הקישור הנכנס מהאפליקציה ולטפל בו בלי תלות נוספת, אבל מומלץ להשתמש בספריית הלקוח של FDL כדי לנתח את קישור העומק. אפשר להזין את קוד הפעולה ישירות מאפליקציה לנייד, בדומה לאופן שבו הוא מוזן בתהליך האינטרנטי שמתואר בקטע התאמה אישית של מטפלי אימייל.

כשמטפלים בפעולות שקשורות לאימייל, כמו אימות כתובת אימייל, צריך לנתח את קוד הפעולה מפרמטר השאילתה oobCode של קישור העומק, ואז להחיל אותו באמצעות applyActionCode כדי שהשינוי ייכנס לתוקף, כלומר כדי שהאימייל יאומת.