שימוש בתוסף Trigger Email

התוסף Trigger Email‏ (firestore-send-email) מאפשר לשלוח אימיילים באופן אוטומטי על סמך מסמכים באוסף Cloud Firestore. הוספת מסמך לאוסף מפעילה את התוסף הזה לשליחת אימייל שנבנה מהשדות של המסמך. בשדות ברמה העליונה של המסמך מצוינים השולח והנמענים של האימייל, כולל האפשרויות to, cc ו-bcc (כל אחת מהן תומכת במזהים ייחודיים). השדה message של המסמך מציין את רכיבי האימייל האחרים, כמו שורת הנושא וגוף האימייל (טקסט פשוט או HTML).

דוגמה בסיסית לכתיבת מסמך שתפעיל את התוסף הזה:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

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

הגדרה לפני ההתקנה

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

  1. מגדירים את שירות האימייל היוצא.

    כשמתקינים את התוסף Trigger Email, צריך לציין את פרטי החיבור והאימות של שרת SMTP, שהתוסף משתמש בו כדי לשלוח אימיילים. בדרך כלל שירות משלוח אימיילים כמו Sendgrid,‏ Mailgun או Mailchimp Transactional Email מספק את הנתונים האלה, אבל יכול להיות שזה גם שרת שאתם מפעילים בעצמכם.

  2. ליצור אוסף של מסמכי אימייל.

    התוסף Trigger Email מאזין למסמכים חדשים בCloud Firestore אוסף שאתם מציינים. כשהתוסף מוצא מסמך חדש, הוא שולח אימייל על סמך השדות של המסמך. אפשר להשתמש בכל אוסף למטרה הזו. בדוגמאות שבדף הזה נעשה שימוש באוסף בשם email.Cloud Firestore

  3. מגדירים כללי אבטחה לאוסף מסמכי האימייל.

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

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

  4. אופציונלי: הגדרת אוסף משתמשים.

    בשימוש הבסיסי בתוסף הזה, מציינים את הנמענים של האימייל על ידי הזנת כתובות האימייל שלהם בשדות to, cc ו-bcc של מסמך ההודעה. לחלופין, אם יש לכם מסד נתונים של משתמשים ב-Cloud Firestore, אתם יכולים לציין נמענים באמצעות מזהי המשתמשים (UID). כדי שהתכונה הזו תפעל, אוסף המשתמשים שלכם צריך לעמוד בקריטריונים הבאים:

    • האיסוף צריך להתבסס על מזהי משתמשים. כלומר, מזהה המסמך של כל מסמך משתמש באוסף חייב להיות Firebase Authentication UID של המשתמש.
    • בכל מסמך של משתמש צריך להיות שדה email שמכיל את כתובת האימייל של המשתמש.

  5. אופציונלי: הגדרת אוסף תבניות.

    אפשר לעבד הודעות אימייל באמצעות תבניות Handlebars. כדי לעשות זאת, תצטרכו Cloud Firestore אוסף שיכיל את התבניות שלכם.

    פרטים נוספים זמינים במאמר שימוש בתבניות Handlebars עם התוסף Trigger Email.

התקנת התוסף

כדי להתקין את התוסף, פועלים לפי השלבים בדף התקנה של Firebase Extension. לסיכום, מבצעים אחת מהפעולות הבאות:

  • Firebase במסוף: לוחצים על הלחצן הבא:

    התקנת התוסף Trigger Email

  • CLI: מריצים את הפקודה הבאה: 

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

במהלך ההתקנה של התוסף, תתבקשו לציין את פרטי החיבור שלכם ל-SMTP ואת אוספי Cloud Firestore שהגדרתם קודם.

שימוש בתוסף

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

דוגמה: שליחת אימייל

כדי לשלוח הודעה פשוטה, מוסיפים מסמך לאוסף ההודעות עם שדה to ושדה message עם התוכן הבא:

to: ['someone@example.com'],
message: {
  subject: 'Hello from Firebase!',
  text: 'This is the plaintext section of the email body.',
  html: 'This is the <code>HTML</code> section of the email body.',
}

שדות השולח והנמען

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

  • ‫from:‎ כתובת האימייל של השולח. אם לא מציינים כתובת בשדה הזה, המערכת משתמשת בפרמטר המוגדר 'כתובת ברירת המחדל של השולח'.
  • ‫replyTo: כתובת האימייל לשליחת תשובות. אם לא מציינים כתובת במסמך, המערכת משתמשת בפרמטר המוגדר 'כתובת ברירת מחדל לשליחת תשובה'.
  • ‫to: כתובת אימייל אחת של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • ‫toUids: מערך שמכיל את מזהי ה-UID של הנמענים.
  • ‫cc: כתובת אימייל אחת של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • ccUids: מערך שמכיל את מזהי ה-UID של הנמענים שקיבלו עותק.
  • ‫bcc: כתובת אימייל של נמען יחיד או מערך שמכיל כמה כתובות אימייל של נמענים.
  • ‫bccUids: מערך שמכיל את מזהי ה-UID של הנמענים שהועברו לעותק מוסתר.
  • headers: אובייקט של שדות כותרת נוספים (לדוגמה, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

הערה: האפשרויות toUids,‏ ccUids ו-bccUids שולחות אימיילים על סמך מזהי משתמש (UID) שמשויכים לכתובות אימייל במסמך Cloud Firestore. כדי להשתמש באפשרויות האלה של נמענים, צריך לציין אוסף Cloud Firestore לפרמטר 'אוסף משתמשים' של התוסף. התוסף יכול לקרוא את השדה email לכל UID שצוין בשדות toUids, ccUids ו/או bccUids.

שדה הודעה

השדה message במסמך מכיל מידע גולמי על המסירה של האימייל. בדרך כלל, רק קוד מהימן שפועל בשרתים שלכם או ב-Cloud Functions אמור לאכלס את השדה הזה (ראו את הקטע 'כללי אבטחה ושליחת אימייל' בהמשך).

המאפיינים הזמינים בשדה message הם:

  • ‫messageId: כותרת של מזהה הודעה באימייל, אם יש כזו.
  • subject: נושא האימייל.
  • ‫text: התוכן של האימייל בטקסט פשוט.
  • ‫html: תוכן ה-HTML של האימייל.
  • ‫amp: תוכן AMP4EMAIL של האימייל.
  • ‫attachments: מערך שמכיל קבצים מצורפים. אפשרויות Nodemailer שנתמכות: מחרוזת utf-8, סוג תוכן מותאם אישית, כתובת URL, מחרוזת מקודדת, URI של נתונים וצומת MIME שנוצר מראש (חשוב לדעת שלא ניתן לגשת מאימייל למערכת הקבצים של שרת הענן).

שימוש מתקדם

מידע נוסף על שימוש מתקדם בתוסף הזה: