Giao diện

Câu hỏi thường gặp (FAQ) — Firebase Notification ​

Câu hỏi chung ​

Firebase Cloud Messaging có miễn phí không? ​

FCM hoàn toàn miễn phí cho việc gửi push notification, không giới hạn số lượng. Phí chỉ phát sinh nếu bạn sử dụng thêm các dịch vụ Firebase khác (Firestore, Storage, v.v.).

Tôi cần tạo Firebase project như thế nào? ​

  1. Truy cập Firebase Console
  2. Nhấn Create a project, đặt tên và chọn tài khoản Google Analytics (tuỳ chọn)
  3. Vào Project Settings → Service accounts → Generate new private key
  4. Tải file JSON — đây chính là Service Account Key cần cấu hình trong plugin

Plugin có hỗ trợ gửi notification đến nhiều user cùng lúc không? ​

Có. Trường receivers trong message chấp nhận mảng user ID. Plugin sẽ truy vấn tất cả FCM token của các user này và gửi đến từng thiết bị song song bằng Promise.allSettled.

Tôi có thể lưu nhiều cấu hình Service Account không? ​

Có. Plugin hỗ trợ lưu nhiều cấu hình trong bảng firebase_service_account_configs (VD: production, staging). Tuy nhiên chỉ cấu hình được đánh dấu isDefault = true mới được dùng để gửi. Khi đổi cấu hình mặc định, plugin tự động reinitialize Firebase SDK.

Service Account JSON có được bảo mật không? ​

Có. Nội dung JSON được mã hoá AES trước khi lưu vào database. Khi admin xem lại trên giao diện, plugin tự giải mã để hiển thị. Private key không bao giờ lưu dạng plaintext.

Tích hợp client ​

Làm sao đăng ký device token từ ứng dụng? ​

Ứng dụng client cần:

  1. Tích hợp Firebase SDK (Android, iOS, hoặc Web)
  2. Xin quyền nhận notification từ user
  3. Lấy FCM token từ Firebase SDK
  4. Gửi token về server qua API firebase_notification_user_token:saveToken:
typescript
await apiClient.request({
  url: 'firebase_notification_user_token:saveToken',
  method: 'POST',
  data: {
    fcmToken: token,
    deviceUUID: deviceId,
  },
});

deviceUUID là gì? Lấy ở đâu? ​

deviceUUID là mã định danh duy nhất cho thiết bị, dùng để phân biệt các device của cùng một user. Cách lấy:

  • Android: Settings.Secure.ANDROID_ID hoặc thư viện react-native-device-info
  • iOS: UIDevice.identifierForVendor hoặc react-native-device-info
  • Web: Tạo UUID lưu trong localStorage

Khi nào cần cập nhật FCM token? ​

FCM token có thể thay đổi khi:

  • User gỡ và cài lại ứng dụng
  • User xoá dữ liệu ứng dụng
  • Token hết hạn (hiếm nhưng có thể xảy ra)

Nên gọi saveToken mỗi khi ứng dụng khởi động để đảm bảo token luôn mới nhất.

Xử lý lỗi thường gặp ​

Thông báo không đến thiết bị ​

Kiểm tra lần lượt:

  1. User có FCM token không? — Kiểm tra bảng firebase_notification_user_token có bản ghi cho user đó
  2. FCM token còn hiệu lực? — Token cũ hoặc token từ ứng dụng đã gỡ sẽ không hoạt động
  3. Ứng dụng cho phép notification? — User phải cấp quyền trong cài đặt hệ điều hành
  4. Service Account đúng project? — Service Account phải thuộc cùng Firebase project mà client đăng ký
  5. iOS: APNs đã cấu hình? — Firebase cần APNs certificate/key để gửi đến iOS

Lỗi "No receivers provided" ​

Trường receivers trong message rỗng hoặc không hợp lệ. Đảm bảo:

  • receivers.value là mảng số (user ID), hoặc
  • message.receivers là mảng user ID

Lỗi "No FCM tokens found for receivers" ​

Các user nhận notification chưa đăng ký device token. Đảm bảo ứng dụng client đã gọi saveToken cho những user này.

Plugin báo lỗi khi kích hoạt ​

Kiểm tra:

  • Plugin notification-manager đã được kích hoạt trước
  • Service Account JSON hợp lệ (đúng format JSON, có đủ trường project_id, private_key, v.v.)
  • Kết nối Internet hoạt động (plugin cần kết nối Firebase để khởi tạo)

Đổi Service Account nhưng notification vẫn gửi bằng cấu hình cũ ​

Đảm bảo cấu hình mới được đánh dấu isDefault = true. Plugin chỉ reinitialize Firebase SDK khi bản ghi có isDefault = true được lưu. Nếu vẫn không hoạt động, thử restart server.

Câu hỏi nâng cao ​

Có thể gửi dữ liệu tuỳ chỉnh kèm notification không? ​

Có. Trường data trong message chấp nhận object hoặc JSON string:

json
{
  "title": "Đơn hàng mới",
  "body": "Bạn có đơn hàng #1234 cần xử lý",
  "url": "/orders/1234",
  "data": { "orderId": 1234, "priority": "high" }
}

Ứng dụng client nhận data trong notification payload và có thể xử lý tuỳ theo logic riêng.

Plugin có tự xoá token hết hạn không? ​

Hiện tại plugin không tự động xoá token hết hạn. Khi gửi thất bại, kết quả trả về status: 'fail'. Bạn có thể xây dựng workflow hoặc cron job để dọn dẹp token cũ dựa trên kết quả gửi.