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

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

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

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

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

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

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

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

כדי להעביר כתובת URL להמשך בצורה מאובטחת, צריך להוסיף את הדומיין של כתובת ה-URL כדומיין מורשה:

  1. במסוף Firebase, עוברים אל Security (אבטחה) > Authentication (אימות) > הכרטיסייה Settings (הגדרות).

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

צריך לספק מופע של 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‏ (`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 של פעולות באימייל זמין במאמר בנושא התאמה אישית של handlers של אימיילים.

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

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

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

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

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

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