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

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

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

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

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

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

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

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

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

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

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

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

  • כשמטפלים בקישור בווידג'טים של פעולות באינטרנט, זהו קישור העומק בפרמטר השאילתה continueUrl.
  • אם הקישור מטופל ישירות באפליקציה, זהו פרמטר השאילתה continueUrl בקישור העומק של הקישור הדינמי.
iOSBundleId מחרוזת מגדיר את מזהה החבילה. המערכת תנסה לפתוח את הקישור באפליקציה של אפל אם היא מותקנת. האפליקציה צריכה להיות רשומה ב-Console. אם לא צוין מזהה חבילה, הערך של השדה הזה מוגדר למזהה החבילה של החבילה הראשית של האפליקציה.
androidPackageName מחרוזת הגדרת שם החבילה ב-Android. המערכת תנסה לפתוח את הקישור באפליקציית Android אם היא מותקנת.
androidInstallApp בוליאני המדיניות הזו מציינת אם להתקין את אפליקציית Android אם המכשיר תומך בה והיא עדיין לא מותקנת. אם השדה הזה מסופק ללא packageName, מוצגת שגיאה שמסבירה שחובה לספק את packageName יחד עם השדה הזה.
androidMinimumVersion מחרוזת הגרסה המינימלית של האפליקציה שנתמכת בתהליך הזה. אם מצוין הערך minimumVersion, ומותקנת גרסה ישנה יותר של האפליקציה, המשתמש מועבר לחנות Play כדי לשדרג את האפליקציה. אפליקציית Android צריכה להיות רשומה ב-Console.
handleCodeInApp בוליאני האם הקישור לפעולה באימייל ייפתח קודם באפליקציה לנייד או בקישור לאינטרנט. ברירת המחדל היא false. אם המדיניות מוגדרת כ-True, הקישור עם קוד הפעולה יישלח כקישור אוניברסלי או כקישור לאפליקציית Android, והאפליקציה תפתח אותו אם היא מותקנת. במקרה של תשובה שגויה, הקוד יישלח קודם לווידג'ט האינטרנטי ואז, אם האפליקציה מותקנת, המשתמש יופנה אליה אחרי שימשיך.
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. מידע נוסף זמין במאמר בנושא קבלת הוראות לקישורים דינמיים בפלטפורמות של אפל.

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

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

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

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

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

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

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

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

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