Sử dụng phần mở rộng Email kích hoạt

Tiện ích Trigger Email (firestore-send-email) cho phép bạn tự động gửi email dựa trên các tài liệu trong một bộ sưu tập Cloud Firestore. Việc thêm một tài liệu vào bộ sưu tập sẽ kích hoạt tiện ích này gửi một email được tạo từ các trường của tài liệu. Các trường cấp cao nhất của tài liệu chỉ định người gửi và người nhận email, bao gồm cả các lựa chọn to, cc và bcc (mỗi lựa chọn đều hỗ trợ UID). Trường message của tài liệu chỉ định các phần tử khác của email, chẳng hạn như dòng tiêu đề và nội dung email (văn bản thuần tuý hoặc HTML).

Sau đây là một ví dụ cơ bản về thao tác ghi tài liệu sẽ kích hoạt tiện ích này:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

Bạn cũng có thể định cấu hình tiện ích này (không bắt buộc) để hiển thị email bằng cách sử dụng mẫu Handlebars.

Thiết lập trước khi cài đặt

Trước khi cài đặt tiện ích, hãy hoàn tất các bước sau:

  1. Thiết lập dịch vụ thư gửi đi.

    Khi cài đặt tiện ích Trigger Email, bạn sẽ cần chỉ định thông tin chi tiết về kết nối và xác thực của một máy chủ SMTP mà tiện ích này dùng để gửi email. Dịch vụ này thường do một dịch vụ gửi email cung cấp, chẳng hạn như Sendgrid, Mailgun hoặc Mailchimp Transactional Email, nhưng cũng có thể là một máy chủ mà bạn tự chạy.

  2. Tạo một bộ sưu tập tài liệu qua email.

    Tiện ích Trigger Email (Gửi email khi có sự kiện kích hoạt) sẽ theo dõi các tài liệu mới trong một bộ sưu tập Cloud Firestore mà bạn chỉ định. Khi tìm thấy một tài liệu mới, tiện ích sẽ gửi email dựa trên các trường của tài liệu. Bạn có thể sử dụng bất kỳ tập hợp Cloud Firestore nào cho mục đích này; các ví dụ trên trang này sử dụng một tập hợp có tên là email.

  3. Thiết lập các quy tắc bảo mật cho bộ sưu tập tài liệu email của bạn.

    Bạn có thể dùng tiện ích này để kích hoạt việc gửi email ngay từ các ứng dụng khách. Tuy nhiên, bạn nên kiểm soát cẩn thận quyền truy cập của ứng dụng vào bộ sưu tập để tránh hành vi sai trái tiềm ẩn (bạn không muốn người dùng có thể gửi email tuỳ ý từ địa chỉ của công ty mình!).

    Các quy tắc bảo mật sẽ khác nhau tuỳ theo từng ứng dụng, nhưng bạn phải luôn đảm bảo rằng email chỉ được gửi đến người nhận dự kiến và nội dung tự do được giữ ở mức tối thiểu. Các mẫu có thể giúp ích trong trường hợp này. Bạn có thể sử dụng các quy tắc bảo mật để xác minh rằng dữ liệu được điền vào mẫu khớp với những gì bạn mong đợi về những gì người dùng được phép kích hoạt.

  4. Không bắt buộc: Thiết lập một bộ sưu tập người dùng.

    Trong phần sử dụng cơ bản của tiện ích này, bạn chỉ định người nhận email bằng cách chỉ định địa chỉ email của họ trong các trường to, cc và bcc của tài liệu thông báo. Ngoài ra, nếu có cơ sở dữ liệu người dùng trong Cloud Firestore, bạn có thể chỉ định người nhận bằng cách sử dụng UID của người dùng. Để tính năng này hoạt động, tập hợp người dùng của bạn phải đáp ứng các tiêu chí sau:

    • Bạn phải lập chỉ mục cho bộ sưu tập dựa trên mã nhận dạng người dùng. Tức là mã nhận dạng tài liệu của mỗi tài liệu người dùng trong bộ sưu tập phải là Firebase Authentication UID của người dùng.
    • Mỗi tài liệu người dùng phải có một trường email chứa địa chỉ email của người dùng.

  5. Không bắt buộc: Thiết lập một bộ sưu tập mẫu.

    Bạn có thể hiển thị email bằng cách sử dụng các mẫu Handlebars. Để làm như vậy, bạn sẽ cần một bộ sưu tập Cloud Firestore để chứa các mẫu của mình.

    Hãy xem bài viết Sử dụng mẫu Handlebars với tiện ích Trigger Email để biết thông tin chi tiết.

Cài đặt tiện ích

Để cài đặt tiện ích, hãy làm theo các bước trên trang Cài đặt Firebase Extension. Tóm lại, hãy thực hiện một trong những thao tác sau:

  • Bảng điều khiển Firebase: Nhấp vào nút sau:

    Cài đặt tiện ích Trigger Email

  • CLI: Chạy lệnh sau: 

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

Khi cài đặt tiện ích này, bạn sẽ được nhắc chỉ định thông tin kết nối SMTP và các bộ sưu tập Cloud Firestore mà bạn đã thiết lập trước đó.

Sử dụng tiện ích

Sau khi cài đặt, tiện ích này sẽ giám sát tất cả các thao tác ghi tài liệu vào bộ sưu tập mà bạn đã định cấu hình. Email được gửi dựa trên nội dung của các trường trong tài liệu. Các trường cấp cao nhất chỉ định người gửi và người nhận email. Trường message chứa thông tin chi tiết về email cần gửi, bao gồm cả nội dung email.

Ví dụ: Gửi email

Để gửi một tin nhắn đơn giản, hãy thêm một tài liệu vào bộ sưu tập tin nhắn của bạn bằng trường to và trường message có nội dung sau:

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.',
}

Trường người gửi và người nhận

Các trường cấp cao nhất của tài liệu cung cấp thông tin về người gửi và người nhận email. Các trường có sẵn là:

  • from: Địa chỉ email của người gửi. Nếu không được chỉ định trong tài liệu, thì sẽ sử dụng thông số "Địa chỉ người gửi mặc định" đã định cấu hình.
  • replyTo: Địa chỉ email trả lời. Nếu không được chỉ định trong tài liệu, thì sẽ sử dụng thông số "Địa chỉ PHẢN HỒI mặc định" đã định cấu hình.
  • to: Một địa chỉ email người nhận duy nhất hoặc một mảng chứa nhiều địa chỉ email người nhận.
  • toUids: Một mảng chứa các UID của người nhận.
  • cc: Một địa chỉ email của người nhận hoặc một mảng chứa nhiều địa chỉ email của người nhận.
  • ccUids: Một mảng chứa UID của người nhận CC.
  • bcc: Một địa chỉ email của người nhận hoặc một mảng chứa nhiều địa chỉ email của người nhận.
  • bccUids: Một mảng chứa UID của người nhận BCC.
  • headers: Một đối tượng của các trường tiêu đề bổ sung (ví dụ: {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

LƯU Ý: Các lựa chọn toUids, ccUids và bccUids gửi email dựa trên mã nhận dạng người dùng được liên kết với địa chỉ email trong một tài liệu Cloud Firestore. Để sử dụng các lựa chọn người nhận này, bạn cần chỉ định một tập hợp Cloud Firestore cho tham số "Tập hợp người dùng" của tiện ích. Sau đó, tiện ích có thể đọc trường email cho từng UID được chỉ định trong các trường toUids, ccUids và/hoặc bccUids.

Trường thông báo

Trường message của tài liệu chứa thông tin gửi thô cho email. Thông thường, trường này chỉ được điền sẵn bởi mã đáng tin cậy chạy trong máy chủ hoặc Cloud Functions của riêng bạn (tham khảo phần "Quy tắc bảo mật và gửi email" bên dưới).

Các thuộc tính có sẵn cho trường message là:

  • messageId: Tiêu đề mã nhận dạng thư của email (nếu có).
  • subject: Tiêu đề của email.
  • text: Nội dung văn bản thuần tuý của email.
  • html: Nội dung HTML của email.
  • amp: Nội dung AMP4EMAIL của email.
  • attachments: Một mảng chứa(các) tệp đính kèm; các lựa chọn Nodemailer được hỗ trợ: chuỗi utf-8, loại nội dung tuỳ chỉnh, URL, chuỗi được mã hoá, URI dữ liệu và nút MIME được tạo trước (lưu ý rằng email của bạn không có quyền truy cập vào hệ thống tệp của máy chủ đám mây).

Sử dụng nâng cao

Tìm hiểu về cách sử dụng tiện ích này ở mức nâng cao hơn: