Cài đặt và sử dụng — Firebase Notification

Tổng quan

Plugin @digiforce-nc/plugin-firebase-notification tích hợp Firebase Cloud Messaging (FCM) vào hệ thống DigiForce, cho phép gửi push notification đến thiết bị Android, iOS và trình duyệt Web. Plugin đăng ký một notification channel type firebase với plugin-notification-manager, quản lý device token (FCM token) cho từng user, và gửi thông báo đẩy đến đúng thiết bị.

Yêu cầu trước khi cài đặt

Plugin @digiforce-nc/plugin-notification-manager đã được kích hoạt
Một Firebase project trên Firebase Console
Service Account Key (JSON) từ Firebase Console

Bước 1: Tạo Firebase project và lấy Service Account Key

Truy cập Firebase Console → Create a project (hoặc chọn project có sẵn)
Vào Project Settings → Service accounts → Generate new private key
Tải file JSON về — đây là Service Account Key cần cấu hình trong plugin

Lưu ý bảo mật

File Service Account Key chứa private key cho phép truy cập toàn bộ Firebase project. Không commit file này vào source control. Plugin sẽ mã hoá nội dung JSON bằng AES trước khi lưu vào database.

Bước 2: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-firebase-notification và bật lên.

Bước 3: Cấu hình Service Account

Sau khi kích hoạt, vào phần cấu hình Firebase Notification trong Settings:

Trường	Mô tả	Bắt buộc
Name	Tên cấu hình (VD: "Production FCM")	✅
Service Account JSON	Nội dung JSON từ file Service Account Key đã tải ở Bước 1	✅
Is Default	Đánh dấu đây là cấu hình mặc định. Chỉ một cấu hình được đặt mặc định tại một thời điểm	❌

Plugin hỗ trợ lưu nhiều cấu hình Service Account (VD: production và staging), nhưng chỉ cấu hình mặc định (isDefault = true) được dùng để gửi notification.

Cơ chế mã hoá

Nội dung Service Account JSON được mã hoá AES trước khi lưu vào bảng firebase_service_account_configs. Khi admin xem lại, plugin tự giải mã để hiển thị. Điều này đảm bảo private key không lưu dạng plaintext trong database.

Bước 4: Đăng ký device token từ ứng dụng client

Ứng dụng mobile hoặc web cần gửi FCM token về server để nhận push notification:

typescript

// Phía client — sau khi lấy FCM token từ Firebase SDK
const response = await apiClient.request({
  url: 'firebase_notification_user_token:saveToken',
  method: 'POST',
  data: {
    fcmToken: 'FCM_TOKEN_TỪ_FIREBASE_SDK',
    deviceUUID: 'MÃ_ĐỊNH_DANH_THIẾT_BỊ',
  },
});

Action saveToken thực hiện upsert: nếu deviceUUID đã tồn tại cho user hiện tại, token sẽ được cập nhật; nếu chưa, một bản ghi mới được tạo.

Database Schema

Bảng `firebase_notification_user_token`

Trường	Kiểu	Mô tả
`userId`	`bigInt`	ID người dùng (khoá ngoại → `users`)
`fcmToken`	`text`	FCM token của thiết bị
`deviceUUID`	`string`	Mã định danh duy nhất của thiết bị

Bảng `firebase_service_account_configs`

Trường	Kiểu	Mô tả
`name`	`string`	Tên cấu hình
`json`	`text`	Nội dung Service Account JSON (đã mã hoá AES)
`isDefault`	`boolean`	Có phải cấu hình mặc định không

Luồng gửi notification

Cấu trúc message gửi đi

Trường	Kiểu	Mô tả
`title`	`string`	Tiêu đề notification
`body`	`string`	Nội dung notification
`url`	`string` (tuỳ chọn)	URL mở khi user tap vào notification
`data`	`object` hoặc `string` (tuỳ chọn)	Dữ liệu tuỳ chỉnh gửi kèm (VD: `{ orderId: 123 }`)
`receivers`	`array`	Danh sách user ID nhận notification

Vòng đời plugin

Sự kiện	Hành vi
load	Import collections, đăng ký channel type `firebase`, đăng ký action `saveToken`, khởi tạo Firebase SDK
afterEnable	Khởi tạo Firebase SDK (lần kích hoạt đầu tiên, table vừa được tạo)
afterDisable	Xoá Firebase App instance để giải phóng tài nguyên
Service Account thay đổi	Tự động reinitialize Firebase SDK với cấu hình mới

Lưu ý quan trọng

iOS cần cấu hình thêm APNs certificate trong Firebase Console để push notification hoạt động
FCM token có thể hết hạn hoặc bị thu hồi — client nên cập nhật token định kỳ
Plugin gửi notification đến tất cả thiết bị của user (một user có thể có nhiều device token)
Nếu tất cả token đều fail, kết quả trả về status: 'fail' kèm lý do chi tiết
Action saveToken yêu cầu người dùng đã đăng nhập (loggedIn)