שימוש בתוסף 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: מערך שמכיל את מזהי המשתמשים של הנמענים שמופיעים בשדה 'עותק'.
  • ‫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 שנוצר מראש (חשוב לזכור שלא ניתן לגשת מאימייל למערכת הקבצים של שרת הענן).

שימוש מתקדם

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