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

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

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

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

היתרונות של התכונה הזו:

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

הפעלה של ActionCodeSettings

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

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

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

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

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

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

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

הדוגמה הבאה ממחישה איך לשלוח קישור לאימות כתובת אימייל שייפתח קודם באפליקציה לנייד. קישור העומק יכיל את מטען הנתונים של כתובת ה-URL להמשך https://www.example.com/checkout?cartId=1234. דומיין הקישור המותאם אישית של Hosting הוא custom-domain.com, וצריך להגדיר אותו לשימוש עם Firebase Hosting.

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',
  },
  // The domain must be configured in Firebase Hosting and owned by the project.
  linkDomain: 'custom-domain.com',
};

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 מותאם אישית.

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

יצירת קישור לאימות כתובת אימייל

כדי ליצור קישור לאימות כתובת אימייל, צריך לספק את כתובת האימייל הקיימת של המשתמש שלא אומתה ואובייקט 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 באמצעות קישורים באימייל כך תוכלו לקבל מידע על השלמת הכניסה אחרי שהמשתמש לוחץ על הקישור ומועבר חזרה לאפליקציה.