การใช้ส่วนขยายอีเมลทริกเกอร์

ส่วนขยายอีเมลทริกเกอร์ (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.',
  },
})

นอกจากนี้ คุณยังกำหนดค่าส่วนขยายนี้ให้แสดงผลอีเมลโดยใช้เทมเพลต Handlebars ได้ด้วย

การตั้งค่าก่อนการติดตั้ง

ก่อนติดตั้งส่วนขยาย ให้ทำตามขั้นตอนต่อไปนี้

1. ตั้งค่าบริการอีเมลขาออก

   เมื่อติดตั้งส่วนขยายอีเมลทริกเกอร์ คุณจะต้องระบุรายละเอียดการเชื่อมต่อและการตรวจสอบสิทธิ์ของเซิร์ฟเวอร์ SMTP ซึ่งส่วนขยายใช้เพื่อส่งอีเมล โดยปกติแล้วบริการนี้จะให้บริการโดยบริการนำส่งอีเมล เช่น Sendgrid, Mailgun หรืออีเมลธุรกรรมของ Mailchimp แต่ก็อาจเป็นเซิร์ฟเวอร์ที่คุณเรียกใช้เองก็ได้

2. สร้างคอลเล็กชันเอกสารอีเมล

   ส่วนขยายอีเมลทริกเกอร์จะรอเอกสารใหม่ในCloud Firestore คอลเล็กชันที่คุณระบุ เมื่อพบเอกสารใหม่ ส่วนขยายจะส่งอีเมลตามช่องของเอกสาร คุณใช้Cloud Firestore คอลเล็กชันใดก็ได้เพื่อวัตถุประสงค์นี้ ตัวอย่างในหน้านี้ใช้คอลเล็กชัน ชื่อ email

3. ตั้งค่ากฎความปลอดภัยสำหรับการรวบรวมเอกสารอีเมล

   คุณสามารถใช้ส่วนขยายนี้เพื่อทริกเกอร์การนำส่งอีเมลจากแอปพลิเคชันไคลเอ็นต์ได้โดยตรง อย่างไรก็ตาม คุณควรควบคุมการเข้าถึงของไคลเอ็นต์ในคอลเล็กชันอย่างระมัดระวังเพื่อหลีกเลี่ยงการละเมิดที่อาจเกิดขึ้น (คุณไม่ต้องการให้ผู้ใช้ส่งอีเมลโดยพลการจากอีเมลของบริษัท)

   กฎความปลอดภัยจะแตกต่างกันไปในแต่ละแอปพลิเคชัน แต่คุณควร ตรวจสอบเสมอว่าอีเมลจะส่งถึงผู้รับที่ต้องการเท่านั้น และ เนื้อหาแบบอิสระจะอยู่ในระดับต่ำสุด เทมเพลตช่วยได้ในกรณีนี้ โดยคุณสามารถใช้กฎความปลอดภัยเพื่อยืนยันว่าข้อมูลที่ป้อนลงในเทมเพลตตรงกับความคาดหวังของคุณเกี่ยวกับสิ่งที่ควรอนุญาตให้ผู้ใช้ทริกเกอร์

4. ไม่บังคับ: ตั้งค่าคอลเล็กชันผู้ใช้

   ภายใต้การใช้งานพื้นฐานของส่วนขยายนี้ คุณจะระบุผู้รับอีเมลได้ โดยการระบุอีเมลของผู้รับในช่อง to, cc และ bcc ของ เอกสารข้อความ อีกทางเลือกหนึ่งคือ หากมีฐานข้อมูลผู้ใช้ใน Cloud Firestore คุณสามารถระบุผู้รับโดยใช้ UID ของผู้ใช้ได้ คอลเล็กชันผู้ใช้ต้องเป็นไปตามเกณฑ์ต่อไปนี้ จึงจะทำงานได้

   • การรวบรวมต้องอิงตามรหัสผู้ใช้ กล่าวคือ รหัสเอกสารของเอกสารผู้ใช้แต่ละรายการในคอลเล็กชันต้องเป็น Firebase AuthenticationUID ของผู้ใช้
   • เอกสารผู้ใช้แต่ละรายการต้องมีฟิลด์ email ที่มีอีเมลของผู้ใช้

5. ไม่บังคับ: ตั้งค่าคอลเล็กชันเทมเพลต

   คุณแสดงผลอีเมลได้โดยใช้เทมเพลต Handlebars โดยคุณจะต้องมีคอลเล็กชัน Cloud Firestore เพื่อเก็บเทมเพลต

   ดูรายละเอียดได้ที่ใช้เทมเพลต Handlebars กับส่วนขยายอีเมลทริกเกอร์

ติดตั้งส่วนขยาย

หากต้องการติดตั้งส่วนขยาย ให้ทำตามขั้นตอนในหน้าติดตั้ง Firebase Extension โดยสรุป ให้ทำอย่างใดอย่างหนึ่งต่อไปนี้

• คอนโซล Firebase: คลิกปุ่มต่อไปนี้

  ติดตั้งส่วนขยายอีเมลทริกเกอร์

• 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: อีเมลสำหรับตอบกลับ หากไม่ได้ระบุในเอกสาร ระบบจะใช้พารามิเตอร์ "ที่อยู่อีเมลเริ่มต้นสำหรับตอบกลับ" ที่กำหนดค่าไว้
• ถึง: อีเมลผู้รับเดียวหรืออาร์เรย์ที่มีอีเมลผู้รับหลายรายการ
• toUids: อาร์เรย์ที่มี UID ของผู้รับ
• cc: อีเมลผู้รับเดียวหรืออาร์เรย์ที่มีอีเมลผู้รับหลายรายการ
• ccUids: อาร์เรย์ที่มี UIDs ของผู้รับสำเนา
• สำเนาลับ: อีเมลผู้รับเดียวหรืออาร์เรย์ที่มีอีเมลผู้รับหลายรายการ
• 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 ที่สร้างไว้ล่วงหน้า (โปรดทราบว่าอีเมลของคุณไม่มีสิทธิ์เข้าถึงระบบไฟล์ของเซิร์ฟเวอร์ระบบคลาวด์)

การใช้งานขั้นสูง

ดูข้อมูลเกี่ยวกับการใช้ส่วนขยายนี้ในระดับที่สูงขึ้น

• ใช้เทมเพลต Handlebars กับส่วนขยายอีเมลทริกเกอร์
• จัดการสถานะการนำส่งด้วยส่วนขยายอีเมลทริกเกอร์