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

התוסף Trigger Email (firestore-send-email) מאפשר לשלוח אימיילים באופן אוטומטי על סמך מסמכים באוסף Cloud Firestore. הוספת מסמך אל האוסף מפעיל את התוסף הזה כדי לשלוח אימייל שנוצר בשדות המסמך. השדות ברמה העליונה של המסמך מציינים את השולח ואת הנמענים של האימייל, כולל האפשרויות to,‏ cc ו-bcc (כל אחת תומכת במזהי UID). בשדה 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.',
  },
})

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

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

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

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

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

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

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

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

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

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

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

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

    • האוסף חייב להיות מוטמע ב-User-ID. כלומר, מזהה המסמך של כל מסמך המשתמש באוסף חייב להיות מזהה ייחודי אוניברסלי (UID) Firebase Authentication של המשתמש.
    • לכל מסמך משתמש צריך להיות שדה email שמכיל את כתובת האימייל של המשתמש.
  5. אופציונלי: מגדירים אוסף של תבניות.

    אפשר לעבד הודעות אימייל באמצעות תבניות של סרגלי אחיזה. לשם כך, נדרש אוסף של 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: כתובת האימייל של השולח. אם לא צוינה כתובת זו במסמך, נעשה שימוש ב"כתובת ברירת המחדל FROM" שהוגדרה הפרמטר.
  • replyTo: כתובת האימייל לשליחת תשובות. אם לא צוינה במסמך, נעשה שימוש ב"כתובת ברירת המחדל לתשובה" שהוגדרה הפרמטר.
  • to: כתובת אימייל יחידה של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • toUids: מערך שמכיל את מזהי ה-UID של הנמענים.
  • cc: כתובת אימייל אחת של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • ccUids: מערך שמכיל את מזהי UID של נמעני ה-CC.
  • bcc: כתובת אימייל אחת של נמען או מערך שמכיל כמה כתובות אימייל של נמענים.
  • bccUids: מערך שמכיל את מזהי UID של נמעני 'עותק מוסתר'.
  • headers:אובייקט של שדות כותרת נוספים (לדוגמה, {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

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

שדה הודעה

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

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

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

שימוש מתקדם

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