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

ส่วนขยายทริกเกอร์อีเมล (firestore-send-email) ช่วยให้คุณส่งอีเมลโดยอัตโนมัติตามเอกสารในคอลเล็กชัน Cloud Firestore การเพิ่มเอกสารลงในคอลเล็กชันจะทริกเกอร์ส่วนขยายนี้ให้ส่งอีเมลที่สร้างจากช่องของเอกสาร ช่องระดับบนสุดของเอกสารจะระบุผู้ส่งและผู้รับอีเมล ซึ่งรวมถึงตัวเลือก to, cc และ bcc (แต่ละตัวเลือกรองรับ UID) ช่อง message ของเอกสารจะระบุองค์ประกอบอื่นๆ ของอีเมล เช่น บรรทัดเรื่องและเนื้อหาอีเมล (ข้อความธรรมดาหรือ HTML)

ต่อไปนี้เป็นตัวอย่างการเขียนเอกสารพื้นฐานที่จะทริกเกอร์ส่วนขยายนี้

admin.firestore().collection('mail').add({
  to: '[e-mail]',
  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 collection ใดก็ได้เพื่อวัตถุประสงค์นี้ ตัวอย่างในหน้านี้ใช้email collection

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

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

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

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

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

   • คอลเล็กชันต้องจัดเก็บตามรหัสผู้ใช้ กล่าวคือ รหัสเอกสารของเอกสารผู้ใช้แต่ละรายการในคอลเล็กชันต้องเป็น Firebase Authentication UID ของผู้ใช้
   • เอกสารผู้ใช้แต่ละรายการต้องมีช่อง 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: ['[e-mail]'],
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: อีเมลสำหรับตอบกลับ หากไม่ได้ระบุในเอกสาร ระบบจะใช้พารามิเตอร์ "ที่อยู่ REPLY-TO เริ่มต้น" ที่กําหนดค่าไว้
• 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 ที่สร้างขึ้นล่วงหน้า (โปรดทราบว่าอีเมลของคุณไม่มีสิทธิ์เข้าถึงระบบไฟล์ของเซิร์ฟเวอร์ระบบคลาวด์)

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

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

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