שימוש בתוסף 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', אבל ייתכן תהיה גם שרת שאתם מנהלים בעצמכם.

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

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

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

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

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

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

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

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

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

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

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

התקנת התוסף

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

כשמתקינים את התוסף, צריך לציין את פרטי החיבור ל-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" שהוגדרה הפרמטר.
  • AnswerTo: כתובת האימייל לתשובה. אם לא צוינה במסמך, נעשה שימוש ב"כתובת ברירת המחדל לתשובה" שהוגדרה הפרמטר.
  • 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 עבור 'אוסף המשתמשים' של התוסף הפרמטר. לאחר מכן, התוסף יוכל לקרוא את השדה email לכל מזהה UID שצוין בשדות toUids,‏ ccUids ו/או bccUids.

שדה הודעה

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

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

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

שימוש מתקדם

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