יצירת קישורים לפעולות באימייל

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

ערכות ה-SDK של לקוחות ב-Firebase מאפשרות לשלוח למשתמשים אימיילים עם קישורים שבעזרתם הם יכולים לאפס סיסמה, לאמת כתובת אימייל ולהיכנס באמצעות אימייל. האימיילים האלה מבוססים על תבניות ונשלחים על ידי Google. אפשר לבצע בהם התאמה אישית מוגבלת.

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

היתרונות של השימוש ב-Google Sheets:

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

איך מפעילים את ActionCodeSettings

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

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

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

כדי לאתחל מכונה של ActionCodeSettings, צריך לספק את הנתונים הבאים:

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

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

  • כשהמערכת מטפלת בקישור בווידג'טים של פעולות באינטרנט, זהו קישור העומק בפרמטר השאילתה continueUrl.
  • כשהקישור מטופל ישירות באפליקציה, זהו פרמטר השאילתה continueUrl בקישורי העומק של הקישור הדינמי.
iOS ({bundleId: string}|undefined) הגדרת מזהה החבילה. המערכת תנסה לפתוח את הקישור באפליקציה של Apple, אם היא מותקנת. האפליקציה צריכה להיות רשומה במסוף.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) הגדרת שם החבילה ב-Android. המערכת תנסה לפתוח את הקישור באפליקציה ל-Android, אם היא מותקנת. אם הערך של installApp מועבר, הוא מציין אם להתקין את אפליקציית Android אם המכשיר תומך בה והאפליקציה עדיין לא מותקנת. אם השדה הזה מסופק ללא packageName, תופיע הודעת שגיאה עם הסבר שצריך לספק את packageName יחד עם השדה הזה. אם minimumVersion צוין וגרסת האפליקציה המותקנת היא קודמת, המשתמש יועבר לחנות Play כדי לשדרג את האפליקציה. האפליקציה ל-Android צריכה להיות רשומה במסוף.
handleCodeInApp (boolean|undefined) אם קישור הפעולה באימייל ייפתח קודם באפליקציה לנייד או בקישור לאינטרנט. ברירת המחדל היא false. אם הערך של הפרמטר הזה מוגדר כ-True, הקישור לקוד הפעולה יישלח כקישור אוניברסלי או כקישור לאפליקציה ל-Android, והאפליקציה תפתח אותו אם היא מותקנת. במקרה של תוצאה שלילית, הקוד יישלח קודם לווידג'ט האינטרנט, ואז המשך הבדיקה יפנה לאפליקציה אם היא מותקנת.
dynamicLinkDomain (string|undefined) הגדרת הדומיין (או תת-הדומיין) של הקישור הדינמי שישמש את הקישור הנוכחי, אם הוא אמור להיפתח באמצעות קישורים דינמיים של Firebase. אפשר להגדיר כמה דומיינים של קישורים דינמיים לכל פרויקט, ולכן השדה הזה מאפשר לבחור דומיין אחד באופן מפורש. אם לא צוין אף דומיין, המערכת תשתמש כברירת מחדל בדומיין הישן ביותר.

בדוגמה הבאה מוסבר איך שולחים קישור אימות באימייל שייפתח קודם באפליקציה לנייד כקישור דינמי של Firebase (אפליקציה ל-Apple‏ com.example.ios או אפליקציה ל-Android‏ com.example.android, שבה האפליקציה תותקן אם היא לא מותקנת כבר, והגרסה המינימלית היא 12). קישור העומק יכיל את עומס העבודה של כתובת ה-URL להמשך https://www.example.com/checkout?cartId=1234. הדומיין של הקישור הדינמי שבו נעשה שימוש הוא coolapp.page.link, וצריך להגדיר אותו לשימוש עם קישורים דינמיים ב-Firebase.

Node.js

const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for
  // this URL must be whitelisted in the Firebase Console.
  url: 'https://www.example.com/checkout?cartId=1234',
  // This must be true for email link sign-in.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios',
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12',
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link',
};

Java

ActionCodeSettings actionCodeSettings = ActionCodeSettings.builder()
    .setUrl("https://www.example.com/checkout?cartId=1234")
    .setHandleCodeInApp(true)
    .setIosBundleId("com.example.ios")
    .setAndroidPackageName("com.example.android")
    .setAndroidInstallApp(true)
    .setAndroidMinimumVersion("12")
    .setDynamicLinkDomain("coolapp.page.link")
    .build();

Python

action_code_settings = auth.ActionCodeSettings(
    url='https://www.example.com/checkout?cartId=1234',
    handle_code_in_app=True,
    ios_bundle_id='com.example.ios',
    android_package_name='com.example.android',
    android_install_app=True,
    android_minimum_version='12',
    dynamic_link_domain='coolapp.page.link',
)

Go

actionCodeSettings := &auth.ActionCodeSettings{
	URL:                   "https://www.example.com/checkout?cartId=1234",
	HandleCodeInApp:       true,
	IOSBundleID:           "com.example.ios",
	AndroidPackageName:    "com.example.android",
	AndroidInstallApp:     true,
	AndroidMinimumVersion: "12",
	DynamicLinkDomain:     "coolapp.page.link",
}

C#‎

var actionCodeSettings = new ActionCodeSettings()
{
    Url = "https://www.example.com/checkout?cartId=1234",
    HandleCodeInApp = true,
    IosBundleId = "com.example.ios",
    AndroidPackageName = "com.example.android",
    AndroidInstallApp = true,
    AndroidMinimumVersion = "12",
    DynamicLinkDomain = "coolapp.page.link",
};

למידע נוסף, קראו את המאמר העברת מצב בפעולות אימייל.

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

Node.js

// Admin SDK API to generate the password reset link.
const userEmail = 'user@example.com';
getAuth()
  .generatePasswordResetLink(userEmail, actionCodeSettings)
  .then((link) => {
    // Construct password reset email template, embed the link and send
    // using custom SMTP server.
    return sendCustomPasswordResetEmail(userEmail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generatePasswordResetLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python

email = 'user@example.com'
link = auth.generate_password_reset_link(email, action_code_settings)
# Construct password reset email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Go

email := "user@example.com"
link, err := client.PasswordResetLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct password reset template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C#‎

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GeneratePasswordResetLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

אחרי היצירה של הקישור, אפשר להוסיף אותו לאימייל המותאם אישית של איפוס הסיסמה, ולאחר מכן לשלוח אותו למשתמש המתאים באמצעות שרת SMTP מותאם אישית.

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

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

Node.js

// Admin SDK API to generate the email verification link.
const useremail = 'user@example.com';
getAuth()
  .generateEmailVerificationLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct email verification template, embed the link and send
    // using custom SMTP server.
    return sendCustomVerificationEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateEmailVerificationLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python

email = 'user@example.com'
link = auth.generate_email_verification_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Go

email := "user@example.com"
link, err := client.EmailVerificationLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct email verification template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C#‎

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateEmailVerificationLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

אחרי היצירה של הקישור, אפשר להוסיף אותו להודעת האימות בהתאמה אישית, ולאחר מכן לשלוח אותה למשתמש המתאים באמצעות שרת SMTP בהתאמה אישית.

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

כדי שתוכלו לאמת משתמשים באמצעות כניסה באמצעות קישור לאימייל, תצטרכו להפעיל את הכניסה באמצעות קישור לאימייל בפרויקט Firebase.

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

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

Node.js

// Admin SDK API to generate the sign in with email link.
const useremail = 'user@example.com';
getAuth()
  .generateSignInWithEmailLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct sign-in with email link template, embed the link and
    // send using custom SMTP server.
    return sendSignInEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateSignInWithEmailLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python

email = 'user@example.com'
link = auth.generate_sign_in_with_email_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Go

email := "user@example.com"
link, err := client.EmailSignInLink(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct sign-in with email link template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C#‎

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateSignInWithEmailLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

אחרי היצירה של הקישור, אפשר להוסיף אותו לאימייל ההרשמה המותאם אישית, ואז לשלוח אותו למשתמש המתאים באמצעות שרת SMTP מותאם אישית.

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