Giao thức HTTP của Giải pháp gửi thông báo qua đám mây của Firebase

Tham số này chỉ định người nhận thư.

Giá trị này có thể là mã thông báo đăng ký của thiết bị, khoá thông báo của nhóm thiết bị hoặc một chủ đề duy nhất (có tiền tố là /topics/). Để gửi đến nhiều chủ đề, hãy sử dụng tham số condition.

Tham số này chỉ định người nhận của thông báo truyền nhiều điểm, một thông báo được gửi đến nhiều mã thông báo đăng ký.

Giá trị này phải là một mảng gồm các mã thông báo đăng ký để gửi thông báo truyền tin nhiều điểm. Mảng phải chứa ít nhất 1 và tối đa 1000 mã thông báo đăng ký. Để gửi thông báo đến một thiết bị, hãy sử dụng tham số to.

Bạn chỉ được phép sử dụng định dạng JSON HTTP cho thông điệp truyền nhiều địa chỉ.

Tham số này chỉ định một biểu thức logic của các điều kiện xác định mục tiêu của thông báo.

Điều kiện được hỗ trợ: Chủ đề, được định dạng là "'yourTopic' trong chủ đề". Giá trị này không phân biệt chữ hoa chữ thường.

Toán tử được hỗ trợ: &&, ||. Hỗ trợ tối đa 2 toán tử cho mỗi tin nhắn chủ đề.

Thông số này không còn được dùng nữa. Thay vào đó, hãy sử dụng to để chỉ định người nhận thư. Để biết thêm thông tin về cách gửi tin nhắn đến nhiều thiết bị, hãy xem tài liệu dành cho nền tảng của bạn.

Tham số này xác định một nhóm thông báo (ví dụ: có collapse_key: "Updates Available") có thể được thu gọn để chỉ thông báo cuối cùng được gửi khi có thể tiếp tục phân phối. Điều này nhằm tránh gửi quá nhiều thông báo giống nhau khi thiết bị kết nối lại mạng hoặc hoạt động trở lại.

Xin lưu ý rằng chúng tôi không đảm bảo thứ tự gửi tin nhắn.

Lưu ý: Tại một thời điểm bất kỳ, bạn chỉ được phép sử dụng tối đa 4 khoá thu gọn khác nhau. Điều này có nghĩa là FCM có thể đồng thời lưu trữ 4 thông báo khác nhau cho mỗi ứng dụng khách. Nếu bạn vượt quá số lượng này, thì không có gì đảm bảo FCM sẽ giữ lại 4 khoá thu gọn nào.

Đặt mức độ ưu tiên của thông báo. Các giá trị hợp lệ là "bình thường" và "cao". Trên các nền tảng của Apple, các mức này tương ứng với mức độ ưu tiên 5 và 10 của APN.

Theo mặc định, thông báo sẽ được gửi ở mức độ ưu tiên cao và thông báo dữ liệu sẽ được gửi ở mức độ ưu tiên bình thường. Mức độ ưu tiên thông thường tối ưu hoá mức tiêu thụ pin của ứng dụng khách và bạn nên sử dụng mức độ ưu tiên này trừ phi cần phân phối ngay lập tức. Đối với các tin nhắn có mức độ ưu tiên thông thường, ứng dụng có thể nhận được tin nhắn với độ trễ không xác định.

Khi một tin nhắn được gửi với mức độ ưu tiên cao, tin nhắn đó sẽ được gửi ngay lập tức và ứng dụng có thể hiển thị thông báo.

Trên các nền tảng của Apple, hãy sử dụng trường này để biểu thị content-available trong tải trọng APN. Khi một thông báo hoặc tin nhắn được gửi và được đặt thành true, một ứng dụng khách không hoạt động sẽ được đánh thức và tin nhắn sẽ được gửi qua APN dưới dạng thông báo im lặng chứ không phải thông qua FCM. Xin lưu ý rằng thông báo không âm thanh trong APN không được đảm bảo sẽ được phân phối và có thể phụ thuộc vào các yếu tố như người dùng bật Chế độ tiết kiệm pin, buộc thoát ứng dụng, v.v. Trên Android, theo mặc định, thông báo dữ liệu sẽ đánh thức ứng dụng. Trên Chrome, hiện không được hỗ trợ.

Trên các nền tảng của Apple, hãy sử dụng trường này để biểu thị mutable-content trong tải trọng APNs. Khi một thông báo được gửi và được đặt thành true, bạn có thể sửa đổi nội dung của thông báo trước khi thông báo đó hiển thị bằng cách sử dụng tiện ích ứng dụng Dịch vụ thông báo. Thông số này sẽ bị bỏ qua đối với Android và web.

Thông số này chỉ định khoảng thời gian (tính bằng giây) mà thông báo sẽ được lưu trữ trong bộ nhớ FCM nếu thiết bị không có kết nối mạng. Thời gian tồn tại tối đa được hỗ trợ là 4 tuần và giá trị mặc định là 4 tuần. Để biết thêm thông tin, hãy xem phần Đặt thời lượng tồn tại của thông báo.

Khi được đặt thành true, tham số này cho phép nhà phát triển kiểm thử một yêu cầu mà không cần thực sự gửi thông báo.

Giá trị mặc định là false.

Thông số này chỉ định các cặp khoá-giá trị tuỳ chỉnh của gói dữ liệu của thông báo.

Ví dụ: với data:{"score":"3x1"}:

Trên các nền tảng của Apple, nếu thông báo được gửi qua APN, thì thông báo đó sẽ đại diện cho các trường dữ liệu tuỳ chỉnh. Nếu được gửi qua FCM, dữ liệu này sẽ được biểu thị dưới dạng từ điển giá trị khoá trong AppDelegate application:didReceiveRemoteNotification:.

Trên Android, thao tác này sẽ dẫn đến một ý định bổ sung có tên score với giá trị chuỗi 3x1.

Khoá không được là từ dành riêng ("from", "message_type" hoặc bất kỳ từ nào bắt đầu bằng "google" hoặc "gcm"). Không sử dụng bất kỳ từ nào được xác định trong bảng này (chẳng hạn như collapse_key).

Bạn nên sử dụng các giá trị thuộc loại chuỗi. Bạn phải chuyển đổi các giá trị trong đối tượng hoặc các loại dữ liệu không phải chuỗi khác (ví dụ: số nguyên hoặc boolean) thành chuỗi.

Tiêu đề của thông báo.

Trường này không hiển thị trên điện thoại và máy tính bảng.

Văn bản nội dung của thông báo.

Âm thanh sẽ phát khi thiết bị nhận được thông báo.

Chuỗi chỉ định các tệp âm thanh trong gói chính của ứng dụng khách hoặc trong thư mục Library/Sounds của vùng chứa dữ liệu của ứng dụng. Hãy xem Thư viện dành cho nhà phát triển iOS để biết thêm thông tin.

Giá trị của huy hiệu trên biểu tượng ứng dụng trên màn hình chính.

Nếu không được chỉ định, huy hiệu sẽ không thay đổi.

Nếu bạn đặt thành 0, huy hiệu sẽ bị xoá.

Hành động liên kết với một lượt nhấp của người dùng vào thông báo.

Tương ứng với category trong tải trọng APN.

Phụ đề của thông báo.

Khoá cho chuỗi nội dung trong tài nguyên chuỗi của ứng dụng để sử dụng nhằm bản địa hoá văn bản nội dung theo ngôn ngữ hiện tại của người dùng.

Tương ứng với loc-key trong tải trọng APN.

Hãy xem phần Tài liệu tham khảo về khoá tải trọng và Bản địa hoá nội dung của thông báo từ xa để biết thêm thông tin.

Giá trị chuỗi biến sẽ được sử dụng thay cho chỉ định định dạng trong body_loc_key để sử dụng nhằm bản địa hoá văn bản nội dung theo ngôn ngữ hiện tại của người dùng.

Tương ứng với loc-args trong tải trọng APN.

Hãy xem phần Tài liệu tham khảo về khoá tải trọng và Bản địa hoá nội dung của thông báo từ xa để biết thêm thông tin.

Khoá cho chuỗi tiêu đề trong tài nguyên chuỗi của ứng dụng để sử dụng nhằm bản địa hoá văn bản tiêu đề theo ngôn ngữ hiện tại của người dùng.

Tương ứng với title-loc-key trong tải trọng APN.

Hãy xem phần Tài liệu tham khảo về khoá tải trọng và Bản địa hoá nội dung của thông báo từ xa để biết thêm thông tin.

Giá trị chuỗi biến sẽ được sử dụng thay cho chỉ định định dạng trong title_loc_key để bản địa hoá văn bản tiêu đề theo ngôn ngữ hiện tại của người dùng.

Tương ứng với title-loc-args trong tải trọng APN.

Hãy xem phần Tài liệu tham khảo về khoá tải trọng và Bản địa hoá nội dung của thông báo từ xa để biết thêm thông tin.

Tiêu đề của thông báo.

Văn bản nội dung của thông báo.

Mã nhận dạng kênh của thông báo (mới trong Android O).

Ứng dụng phải tạo một kênh có mã nhận dạng kênh này trước khi nhận được bất kỳ thông báo nào có mã nhận dạng kênh này.

Nếu bạn không gửi mã kênh này trong yêu cầu hoặc nếu ứng dụng chưa tạo mã kênh được cung cấp, FCM sẽ sử dụng mã kênh được chỉ định trong tệp kê khai ứng dụng.

Biểu tượng của thông báo.

Đặt biểu tượng thông báo thành myicon cho tài nguyên có thể vẽ myicon. Nếu bạn không gửi khoá này trong yêu cầu, FCM sẽ hiển thị biểu tượng trình chạy được chỉ định trong tệp kê khai ứng dụng.

Âm thanh sẽ phát khi thiết bị nhận được thông báo.

Hỗ trợ "default" hoặc tên tệp của tài nguyên âm thanh đi kèm trong ứng dụng. Các tệp âm thanh phải nằm trong /res/raw/.

Giá trị nhận dạng dùng để thay thế các thông báo hiện có trong ngăn thông báo.

Nếu không được chỉ định, mỗi yêu cầu sẽ tạo một thông báo mới.

Nếu được chỉ định và một thông báo có cùng thẻ đang hiển thị, thì thông báo mới sẽ thay thế thông báo hiện có trong ngăn thông báo.

Màu biểu tượng của thông báo, được thể hiện ở định dạng #rrggbb.

Hành động liên kết với một lượt nhấp của người dùng vào thông báo.

Nếu được chỉ định, một hoạt động có bộ lọc ý định phù hợp sẽ được khởi chạy khi người dùng nhấp vào thông báo.

Khoá cho chuỗi nội dung trong tài nguyên chuỗi của ứng dụng để sử dụng nhằm bản địa hoá văn bản nội dung theo ngôn ngữ hiện tại của người dùng.

Hãy xem phần Tài nguyên chuỗi để biết thêm thông tin.

Giá trị chuỗi biến sẽ được sử dụng thay cho chỉ định định dạng trong body_loc_key để sử dụng nhằm bản địa hoá văn bản nội dung theo ngôn ngữ hiện tại của người dùng.

Hãy xem phần Định dạng và định kiểu để biết thêm thông tin.

Khoá cho chuỗi tiêu đề trong tài nguyên chuỗi của ứng dụng để sử dụng nhằm bản địa hoá văn bản tiêu đề theo ngôn ngữ hiện tại của người dùng.

Hãy xem phần Tài nguyên chuỗi để biết thêm thông tin.

Giá trị chuỗi biến sẽ được sử dụng thay cho chỉ định định dạng trong title_loc_key để bản địa hoá văn bản tiêu đề theo ngôn ngữ hiện tại của người dùng.

Hãy xem phần Định dạng và định kiểu để biết thêm thông tin.

Tiêu đề của thông báo.

Văn bản nội dung của thông báo.

URL cần sử dụng cho biểu tượng của thông báo.

Hành động liên kết với một lượt nhấp của người dùng vào thông báo.

Tất cả giá trị URL đều phải sử dụng giao thức HTTPS.

Thông số này chỉ định các ứng dụng khách (mã thông báo đăng ký) nhận được thông báo.

Chỉ được phép gửi thông báo đa hướng (gửi đến nhiều mã thông báo đăng ký) bằng định dạng JSON HTTP.

Tham số này chỉ định các cặp khoá-giá trị của tải trọng của thông báo. Không có giới hạn về số lượng tham số khoá-giá trị, nhưng tổng kích thước thông báo có giới hạn là 4096 byte.

Ví dụ: trong Android, "data.score"."3x1" sẽ dẫn đến một ý định bổ sung có tên là score với giá trị chuỗi là 3x1.

Khoá không được là từ dành riêng ("from", "message_type" hoặc bất kỳ từ nào bắt đầu bằng "google" hoặc "gcm"). Không sử dụng bất kỳ từ nào được xác định trong bảng này (chẳng hạn như collapse_key).

• message_id: Chuỗi chỉ định mã nhận dạng duy nhất cho mỗi thông báo được xử lý thành công.
• error: Chuỗi chỉ định lỗi xảy ra khi xử lý thông báo cho người nhận. Bạn có thể xem các giá trị có thể có trong bảng 9.

• Nếu ứng dụng khách huỷ đăng ký với FCM.
• Nếu ứng dụng khách tự động bị huỷ đăng ký, điều này có thể xảy ra nếu người dùng gỡ cài đặt ứng dụng. Ví dụ: trên iOS, nếu Dịch vụ phản hồi APNs báo cáo mã thông báo APNs là không hợp lệ.
• Nếu mã thông báo đăng ký hết hạn (ví dụ: Google có thể quyết định làm mới mã thông báo đăng ký hoặc mã thông báo APNs đã hết hạn đối với thiết bị iOS).
• Nếu ứng dụng khách được cập nhật nhưng phiên bản mới chưa được định cấu hình để nhận thông báo.

• Thiếu tiêu đề uỷ quyền hoặc có cú pháp không hợp lệ trong yêu cầu HTTP.
• Dự án Firebase mà khoá máy chủ được chỉ định thuộc về không chính xác.
• Chỉ khoá máy chủ cũ – yêu cầu bắt nguồn từ một máy chủ không có trong danh sách cho phép trong phần IP của khoá máy chủ.

Máy chủ không thể xử lý yêu cầu kịp thời. Thử gửi lại yêu cầu đó, nhưng bạn phải:

• Tuân thủ tiêu đề Retry-After nếu tiêu đề này có trong phản hồi từ Máy chủ kết nối FCM.
• Triển khai thuật toán thời gian đợi luỹ thừa trong cơ chế thử lại. (ví dụ: nếu bạn đợi một giây trước khi thử lại lần đầu, hãy đợi ít nhất hai giây trước lần thử lại tiếp theo, sau đó là 4 giây, v.v.). Nếu bạn gửi nhiều tin nhắn, hãy trì hoãn từng tin nhắn một cách độc lập thêm một khoảng thời gian ngẫu nhiên để tránh gửi yêu cầu mới cho tất cả tin nhắn cùng một lúc.

Những người gửi gây ra vấn đề có nguy cơ bị đưa vào danh sách đen.

Tỷ lệ tin nhắn gửi đến một thiết bị cụ thể quá cao. Nếu một ứng dụng của Apple gửi thông báo với tốc độ vượt quá giới hạn của APN, thì ứng dụng đó có thể nhận được thông báo lỗi này

Giảm số lượng tin nhắn gửi đến thiết bị này và sử dụng thời gian đợi luỹ thừa để thử gửi lại.