Giao diện

Câu hỏi thường gặp — Notifications (Legacy) ​

Sử dụng chung ​

Nên dùng plugin này hay plugin-notification-manager? ​

Nếu bạn đang bắt đầu dự án mới, luôn chọn plugin-notification-manager. Plugin đó hỗ trợ multi-channel (email, SMS, push notification), template engine nâng cao, subscription preferences, và kiến trúc plugin channel mở rộng.

plugin-notifications chỉ nên dùng khi:

  • Dự án legacy đã tích hợp sẵn và chưa có kế hoạch migrate
  • Cần gửi email đơn giản qua SMTP mà không cần multi-channel

Có thể dùng cả hai plugin cùng lúc không? ​

Về mặt kỹ thuật thì có thể, vì hai plugin sử dụng Collection riêng biệt. Tuy nhiên, không khuyến nghị vì:

  • Dễ gây nhầm lẫn khi cấu hình (hai nơi quản lý thông báo)
  • Người dùng có thể nhận thông báo trùng lặp
  • Tăng độ phức tạp khi bảo trì

Nên chọn một hệ thống và sử dụng nhất quán.

Cấu hình SMTP ​

Làm sao cấu hình Gmail SMTP? ​

Gmail yêu cầu sử dụng App Password thay vì mật khẩu tài khoản thông thường:

  1. Bật 2-Step Verification trong tài khoản Google
  2. Vào App Passwords và tạo password mới cho ứng dụng "Mail"
  3. Cấu hình notification_services.options:
json
{
  "host": "smtp.gmail.com",
  "port": 465,
  "secure": true,
  "from": "your-email@gmail.com",
  "auth": {
    "user": "your-email@gmail.com",
    "pass": "xxxx-xxxx-xxxx-xxxx"
  }
}

Email gửi đi bị vào Spam, phải làm sao? ​

Một số nguyên nhân phổ biến:

  • Thiếu SPF/DKIM record cho domain gửi — cần cấu hình DNS
  • Địa chỉ from không khớp với domain SMTP — Gmail và nhiều provider yêu cầu khớp
  • Nội dung email chứa nhiều HTML hoặc link đáng ngờ — giảm thiểu link tracking
  • IP gửi bị blacklist — kiểm tra tại MXToolbox

Có hỗ trợ giao thức nào ngoài SMTP không? ​

Không. Plugin này chỉ hỗ trợ SMTP thông qua thư viện nodemailer. Nếu cần gửi qua API (SendGrid, Mailgun, AWS SES API mode), hãy chuyển sang plugin-notification-manager.

Template và nội dung ​

Body template hỗ trợ cú pháp gì? ​

Plugin sử dụng lodash.template để render nội dung. Cú pháp:

Cú phápMô tảVí dụ
<%= value %>Chèn giá trị (escaped HTML)<%= userName %>
<%- value %>Chèn giá trị (raw, không escape)<%- htmlContent %>
<% code %>Chạy JavaScript<% if (vip) { %> VIP <% } %>

Làm sao truyền dữ liệu vào template? ​

Truyền trực tiếp qua tham số của notification.send():

typescript
// Body trong DB: "Xin chào <%= name %>, đơn hàng #<%= orderId %>"
await notification.send({
  name: 'Nguyễn Văn A',
  orderId: '12345',
});

Người nhận (Receivers) ​

Có thể lấy danh sách người nhận từ Collection khác không? ​

Có. Sử dụng receiver_options với fromTable:

json
{
  "fromTable": "users",
  "filter": { "role": "manager" },
  "dataField": "email"
}

Plugin sẽ truy vấn Collection users, lọc theo filter, và lấy giá trị từ trường dataField (ở đây là email) làm danh sách người nhận.

Gửi email cho nhiều người nhận có nhanh không? ​

Plugin gửi tuần tự với delay 100ms giữa mỗi email. Với 100 người nhận, thời gian tối thiểu là ~10 giây (chưa tính thời gian SMTP response). Đây là hạn chế thiết kế của plugin legacy — nếu cần gửi batch lớn, nên dùng plugin-notification-manager với hàng đợi (queue) chuyên dụng.

Xử lý lỗi ​

Email gửi thất bại có được retry không? ​

Không. Plugin không có cơ chế retry tự động. Khi gửi thất bại:

  • Log được ghi vào notification_logs với state: 'fail'
  • Plugin tiếp tục gửi cho người nhận tiếp theo
  • Bạn cần kiểm tra log thủ công và gửi lại nếu cần

Làm sao kiểm tra log gửi thông báo? ​

Truy vấn Collection notification_logs qua API hoặc Collection Manager:

http
GET /api/notification_logs:list?filter={"state":"fail"}&sort=-createdAt

Mỗi log chứa:

  • receiver: địa chỉ email người nhận
  • state: "success" hoặc "fail"
  • response: chi tiết response từ SMTP server