Firebase Cloud Messaging (FCM) cung cấp nhiều lựa chọn và chức năng nhắn tin. Thông tin trên trang này nhằm giúp bạn hiểu các loại thông báo FCM và những việc bạn có thể làm với các thông báo đó.
Loại thông báo
Với FCM, bạn có thể gửi 2 loại thông báo cho khách hàng:
- Thông báo, đôi khi được coi là "thông báo hiển thị". SDK FCM sẽ tự động xử lý những việc này.
- Thông báo dữ liệu do ứng dụng khách xử lý.
Thông báo chứa một bộ khoá được xác định trước mà người dùng có thể nhìn thấy. Ngược lại, thông báo dữ liệu chỉ chứa các cặp khoá-giá trị tuỳ chỉnh do người dùng xác định. Thông báo có thể chứa một trọng tải dữ liệu không bắt buộc. Tải trọng tối đa cho cả hai loại thông báo là 4096 byte, ngoại trừ khi gửi thông báo từ bảng điều khiển Firebase, bảng điều khiển này áp dụng giới hạn 1000 ký tự.
| Trường hợp sử dụng | Cách gửi | |
|---|---|---|
| Thông báo | FCM SDK hiển thị thông báo cho các thiết bị của người dùng cuối thay cho ứng dụng khách khi ứng dụng này đang chạy ở chế độ nền. Nếu không, nếu ứng dụng đang chạy ở nền trước khi nhận được thông báo, thì mã của ứng dụng sẽ xác định hành vi. Thông báo có một tập hợp khoá được xác định trước mà người dùng có thể thấy và một tải trọng dữ liệu không bắt buộc gồm các cặp khoá-giá trị tuỳ chỉnh. |
|
| Thông báo dữ liệu | Ứng dụng khách chịu trách nhiệm xử lý thông báo dữ liệu. Thông báo dữ liệu chỉ có các cặp khoá-giá trị tuỳ chỉnh mà không có tên khoá dành riêng (xem bên dưới). | Trong một môi trường đáng tin cậy như
Cloud Functions
hoặc máy chủ ứng dụng của bạn, hãy sử dụng Admin SDK hoặc FCM Server Protocols. Trong yêu cầu gửi, hãy đặt khoá data.
|
Sử dụng thông báo khi bạn muốn SDK FCM xử lý việc tự động hiển thị thông báo khi ứng dụng của bạn đang chạy ở chế độ nền. Sử dụng thông báo dữ liệu khi bạn muốn xử lý thông báo bằng mã ứng dụng khách của riêng mình.
FCM có thể gửi một thông báo, trong đó có phần tải dữ liệu không bắt buộc. Trong những trường hợp như vậy, FCM sẽ xử lý việc hiển thị tải trọng thông báo và ứng dụng khách sẽ xử lý tải trọng dữ liệu.
Thông báo
Để kiểm thử hoặc để tiếp thị và thu hút lại người dùng, bạn có thể gửi thông báo bằng bảng điều khiển Firebase. Bảng điều khiển Firebase cung cấp thử nghiệm A/B dựa trên số liệu phân tích để giúp bạn tinh chỉnh và cải thiện thông điệp tiếp thị.
Để gửi thông báo theo phương thức lập trình bằng Admin SDK hoặc giao thức FCM, hãy đặt khoá notification bằng bộ khoá-giá trị được xác định trước cần thiết cho phần thông báo mà người dùng nhìn thấy. Ví dụ: sau đây là một thông báo được định dạng JSON trong ứng dụng nhắn tin tức thời. Người dùng có thể thấy một thông báo có tiêu đề "Bồ Đào Nha gặp Đan Mạch" và văn bản "trận đấu hay!" trên thiết bị:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"Portugal vs. Denmark",
"body":"great match!"
}
}
}Thông báo được gửi đến khay thông báo khi ứng dụng chạy trong nền. Đối với các ứng dụng ở nền trước, thông báo sẽ được xử lý bằng một hàm gọi lại.
Hãy xem tài liệu tham khảo về đối tượng thông báo Giao thức HTTP phiên bản 1 để biết danh sách đầy đủ các khoá được xác định trước có sẵn để tạo thông báo.
Thông báo dữ liệu
Bạn có thể tuỳ ý sử dụng tải trọng FCM data để triển khai sơ đồ mã hoá mà bạn chọn. Đảm bảo rằng bạn không sử dụng bất kỳ từ nào được đặt trước trong các cặp khoá-giá trị tuỳ chỉnh. Các từ dành riêng bao gồm "from", "notification", "message_type" hoặc bất kỳ từ nào bắt đầu bằng "google" hoặc "gcm".
Ví dụ: sau đây là một thông báo ở định dạng JSON trong cùng một ứng dụng nhắn tin tức thời như trên, trong đó thông tin được đóng gói trong khoá data chung và ứng dụng khách dự kiến sẽ diễn giải nội dung:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data":{
"Nick" : "Mario",
"body" : "great match!",
"Room" : "PortugalVSDenmark"
}
}
}Ví dụ trên cho thấy cách sử dụng trường data cấp cao nhất hoặc trường chung. Trường này được các ứng dụng diễn giải trên mọi nền tảng nhận được thông báo.
Trên mỗi nền tảng, ứng dụng khách sẽ nhận được tải trọng dữ liệu trong một hàm gọi lại.
Thông báo có tải trọng dữ liệu không bắt buộc
Bằng cả phương thức lập trình hoặc thông qua bảng điều khiển Firebase, bạn có thể gửi thông báo chứa một tải trọng tuỳ chọn gồm các cặp khoá-giá trị tuỳ chỉnh. Trong Trình soạn thông báo, hãy sử dụng các trường Dữ liệu tuỳ chỉnh trong Tuỳ chọn nâng cao.
Hành vi của ứng dụng khi nhận được những thông báo có cả tải trọng thông báo và dữ liệu phụ thuộc vào việc ứng dụng đang ở chế độ nền hay chế độ nền trước – về cơ bản, liệu ứng dụng có đang hoạt động tại thời điểm nhận hay không.
- Khi ở chế độ nền, các ứng dụng sẽ nhận được tải trọng thông báo trong khay thông báo và chỉ xử lý tải trọng dữ liệu khi người dùng nhấn vào thông báo.
- Khi ở nền trước, ứng dụng của bạn sẽ nhận được một đối tượng thông báo có cả hai tải trọng.
Sau đây là một thông báo có định dạng JSON chứa cả khoá notification và khoá data:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"Portugal vs. Denmark",
"body":"great match!"
},
"data" : {
"Nick" : "Mario",
"Room" : "PortugalVSDenmark"
}
}
}Tuỳ chỉnh thông điệp trên nhiều nền tảng
Cả Firebase Admin SDK và giao thức HTTP FCM phiên bản 1 đều cho phép các yêu cầu về thông báo của bạn đặt tất cả các trường có trong đối tượng message. Chẳng hạn như:
- một tập hợp các trường chung mà tất cả các phiên bản ứng dụng nhận được thông báo sẽ diễn giải.
- các tập hợp trường dành riêng cho nền tảng, chẳng hạn như
AndroidConfigvàWebpushConfig, chỉ được các phiên bản ứng dụng chạy trên nền tảng đã chỉ định diễn giải.
Các khối dành riêng cho nền tảng giúp bạn linh hoạt tuỳ chỉnh thông báo cho các nền tảng khác nhau để đảm bảo rằng thông báo được xử lý đúng cách khi nhận được. Phần phụ trợ FCM sẽ xem xét tất cả các tham số được chỉ định và tuỳ chỉnh thông báo cho từng nền tảng.
Trường hợp sử dụng các trường chung
Sử dụng các trường phổ biến khi bạn:
- Nhắm đến các phiên bản ứng dụng trên tất cả các nền tảng – Apple, Android và web
- Gửi thông báo đến các chủ đề
Tất cả các phiên bản ứng dụng, bất kể nền tảng nào, đều có thể diễn giải các trường chung sau:
Trường hợp nên sử dụng các trường dành riêng cho nền tảng
Hãy sử dụng các trường dành riêng cho nền tảng khi bạn muốn:
- Chỉ gửi các trường đến một số nền tảng cụ thể
- Gửi các trường dành riêng cho nền tảng ngoài các trường chung
Bất cứ khi nào bạn chỉ muốn gửi giá trị đến các nền tảng cụ thể, hãy không sử dụng các trường chung mà hãy sử dụng các trường dành riêng cho nền tảng. Ví dụ: để chỉ gửi thông báo đến các nền tảng của Apple và web mà không gửi đến Android, bạn phải sử dụng 2 nhóm trường riêng biệt, một nhóm cho Apple và một nhóm cho web.
Khi bạn gửi thư có lựa chọn phân phối cụ thể, hãy sử dụng các trường dành riêng cho nền tảng để đặt các lựa chọn đó. Bạn có thể chỉ định các giá trị khác nhau cho mỗi nền tảng nếu muốn. Tuy nhiên, ngay cả khi muốn đặt cùng một giá trị trên các nền tảng, bạn vẫn phải sử dụng các trường dành riêng cho nền tảng. Điều này là do mỗi nền tảng có thể diễn giải giá trị này theo cách hơi khác nhau – ví dụ: thời gian tồn tại được đặt trên Android dưới dạng thời gian hết hạn tính bằng giây, trong khi trên Apple, thời gian này được đặt dưới dạng ngày hết hạn.
Ví dụ: thông báo có các lựa chọn phân phối dành riêng cho nền tảng
Yêu cầu gửi v1 sau đây sẽ gửi tiêu đề và nội dung thông báo chung đến tất cả các nền tảng, nhưng cũng gửi một số chế độ ghi đè dành riêng cho nền tảng. Cụ thể, yêu cầu:
- đặt thời gian tồn tại dài cho các nền tảng Android và Web, đồng thời đặt mức độ ưu tiên của thông báo APNs (nền tảng Apple) ở mức thấp
- đặt các khoá thích hợp để xác định kết quả của một lượt nhấn của người dùng vào thông báo trên Android và Apple – lần lượt là
click_actionvàcategory.
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Match update", "body":"Arsenal goal in added time, score is now 3-0" }, "android":{ "ttl":"86400s", "notification"{ "click_action":"OPEN_ACTIVITY_1" } }, "apns": { "headers": { "apns-priority": "5", }, "payload": { "aps": { "category": "NEW_MESSAGE_CATEGORY" } } }, "webpush":{ "headers":{ "TTL":"86400" } } } }
Hãy xem tài liệu tham khảo HTTP phiên bản 1 để biết đầy đủ thông tin chi tiết về các khoá có trong các khối dành riêng cho nền tảng trong nội dung thông báo. Để biết thêm thông tin về cách tạo yêu cầu gửi có chứa nội dung thư, hãy xem phần Tạo yêu cầu gửi.
Phương thức giao hàng
FCM cung cấp một bộ lựa chọn phân phối cụ thể cho các tin nhắn được gửi đến thiết bị Android, đồng thời cho phép các lựa chọn tương tự trên nền tảng Apple và web. Ví dụ: hành vi của thông báo "có thể thu gọn" được hỗ trợ trên Android thông qua FCM's collapse_key, trên Apple thông qua apns-collapse-id và trên JavaScript/Web thông qua Topic. Để biết thông tin chi tiết, hãy xem phần mô tả trong phần này và tài liệu tham khảo có liên quan.
Đặt mức độ ưu tiên của thư
Bạn có hai lựa chọn để chỉ định mức độ ưu tiên phân phối cho các thông báo truyền xuống: mức độ ưu tiên bình thường và mức độ ưu tiên cao. Mặc dù hành vi có khác biệt một chút giữa các nền tảng, nhưng việc phân phối thông báo có mức độ ưu tiên bình thường và cao hoạt động như sau:
Mức độ ưu tiên bình thường. Thông báo có mức độ ưu tiên bình thường sẽ được gửi ngay khi ứng dụng chạy ở nền trước. Đối với các ứng dụng chạy ở chế độ nền, việc gửi có thể bị chậm trễ. Đối với những thông báo ít khẩn cấp hơn, chẳng hạn như thông báo về email mới, việc duy trì trạng thái đồng bộ hoá giao diện người dùng hoặc đồng bộ hoá dữ liệu ứng dụng ở chế độ nền, hãy chọn mức độ ưu tiên phân phối bình thường.
Mức độ ưu tiên cao. FCM cố gắng gửi ngay các thông báo có mức độ ưu tiên cao, ngay cả khi thiết bị ở Chế độ nghỉ. Thông báo có mức độ ưu tiên cao dành cho nội dung có giới hạn thời gian và người dùng có thể nhìn thấy.
Dưới đây là ví dụ về một thông báo có mức độ ưu tiên bình thường được gửi qua giao thức HTTP phiên bản 1 FCM để thông báo cho người đăng ký tạp chí rằng có nội dung mới có thể tải xuống:
{
"message":{
"topic":"subscriber-updates",
"notification":{
"body" : "This week's edition is now available.",
"title" : "NewsMagazine.com",
},
"data" : {
"volume" : "3.21.15",
"contents" : "http://www.news-magazine.com/world-week/21659772"
},
"android":{
"priority":"normal"
},
"apns":{
"headers":{
"apns-priority":"5"
}
},
"webpush": {
"headers": {
"Urgency": "high"
}
}
}
}Để biết thêm thông tin chi tiết theo từng nền tảng về cách đặt mức độ ưu tiên cho thông báo:
- Tài liệu về APN
- Đặt và quản lý mức độ ưu tiên của tin nhắn (Android)
- Mức độ khẩn cấp của thông báo đẩy trên web
Các trường hợp sử dụng quan trọng trong cuộc sống
Các API FCM không được thiết kế cho cảnh báo khẩn cấp hoặc các hoạt động có rủi ro cao khác mà việc sử dụng hoặc lỗi của API có thể dẫn đến tử vong, thương tích cá nhân hoặc huỷ hoại môi trường (chẳng hạn như việc vận hành cơ sở hạt nhân, hệ thống kiểm soát không lưu hoặc hệ thống trợ sinh). Mọi hành vi sử dụng như vậy đều bị nghiêm cấm theo Mục 4. a. 7 của Điều khoản dịch vụ. Bạn hoàn toàn chịu trách nhiệm quản lý việc tuân thủ Điều khoản của ứng dụng và mọi thiệt hại do việc không tuân thủ của bạn gây ra. Google cung cấp các API "nguyên trạng" và giữ quyền ngừng cung cấp các API hoặc bất kỳ phần hay tính năng nào hoặc quyền truy cập của bạn vào đó, với bất kỳ lý do nào và tại bất kỳ thời điểm nào mà không phải chịu trách nhiệm pháp lý hoặc nghĩa vụ khác với bạn hoặc người dùng của bạn.
Đặt thời gian tồn tại của thông báo
FCM thường gửi tin nhắn ngay sau khi tin nhắn được gửi. Tuy nhiên, không phải lúc nào bạn cũng có thể làm được điều này. Ví dụ: nếu nền tảng là Android, thì thiết bị có thể đã tắt, không có mạng hoặc không dùng được. Hoặc FCM có thể cố ý trì hoãn các thông báo để ngăn ứng dụng tiêu thụ quá nhiều tài nguyên và ảnh hưởng tiêu cực đến thời lượng pin.
Khi điều này xảy ra, FCM sẽ lưu trữ thông báo và gửi thông báo đó ngay khi có thể. Mặc dù điều này không sao trong hầu hết các trường hợp, nhưng có một số ứng dụng mà thông báo đến muộn cũng có thể không bao giờ được gửi. Ví dụ: nếu thông báo là thông báo về cuộc gọi đến hoặc cuộc gọi video, thì thông báo đó chỉ có ý nghĩa trong một khoảng thời gian ngắn trước khi cuộc gọi kết thúc. Hoặc nếu là lời mời tham dự một sự kiện, thì thông báo đó sẽ vô ích nếu bạn nhận được sau khi sự kiện kết thúc.
Trên Android và Web/JavaScript, bạn có thể chỉ định tuổi thọ tối đa của một thông báo. Giá trị phải là khoảng thời gian từ 0 đến 2.419.200 giây (28 ngày) và tương ứng với khoảng thời gian tối đa mà FCM lưu trữ và cố gắng gửi thông báo. Những yêu cầu không có trường này sẽ mặc định là khoảng thời gian tối đa 4 tuần.
Dưới đây là một số cách có thể sử dụng tính năng này:
- Cuộc gọi đến qua tính năng trò chuyện video
- Sự kiện lời mời hết hạn
- Sự kiện trên lịch
Một lợi thế khác của việc chỉ định thời gian tồn tại của một thông báo là FCM không áp dụng tính năng điều tiết thông báo có thể thu gọn cho các thông báo có giá trị thời gian tồn tại là 0 giây.
FCM cung cấp cách xử lý tốt nhất cho những thông báo phải được gửi "ngay lập tức". Xin lưu ý rằng giá trị time_to_live bằng 0 có nghĩa là những thông báo không thể gửi ngay sẽ bị loại bỏ. Tuy nhiên, vì những thông báo như vậy không bao giờ được lưu trữ, nên điều này mang lại độ trễ thấp nhất khi gửi thông báo.
Sau đây là ví dụ về một yêu cầu có TTL:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data":{
"Nick" : "Mario",
"body" : "great match!",
"Room" : "PortugalVSDenmark"
},
"apns":{
"headers":{
"apns-expiration":"1604750400"
}
},
"android":{
"ttl":"4500s"
},
"webpush":{
"headers":{
"TTL":"4500"
}
}
}
}Thời gian tồn tại của một thông báo
Khi một máy chủ ứng dụng đăng một thông báo lên FCM và nhận lại một mã nhận dạng thông báo, điều đó không có nghĩa là thông báo đó đã được gửi đến thiết bị. Thay vào đó, điều này có nghĩa là yêu cầu đã được chấp nhận để phân phối. Điều gì xảy ra với thông báo sau khi được chấp nhận phụ thuộc vào nhiều yếu tố.
Trong trường hợp tốt nhất, nếu thiết bị được kết nối với FCM, màn hình đang bật và không có hạn chế nào về việc điều tiết, thì thông báo sẽ được gửi ngay lập tức.
Nếu thiết bị được kết nối nhưng ở chế độ Nghỉ, thì FCM sẽ lưu trữ một thông báo có mức độ ưu tiên thấp cho đến khi thiết bị thoát khỏi chế độ Nghỉ. Đó là lúc cờ collapse_key đóng vai trò: nếu đã có một thông báo có cùng khoá thu gọn (và mã thông báo đăng ký) được lưu trữ và đang chờ được gửi, thì thông báo cũ sẽ bị loại bỏ và thông báo mới sẽ thay thế thông báo cũ (tức là thông báo cũ sẽ bị thông báo mới thu gọn). Tuy nhiên, nếu bạn không đặt khoá thu gọn, cả thông báo mới và cũ đều được lưu trữ để gửi trong tương lai.
Nếu thiết bị không kết nối với FCM, thì thông báo sẽ được lưu trữ cho đến khi kết nối được thiết lập (vẫn tuân theo các quy tắc về khoá thu gọn). Khi một kết nối được thiết lập, FCM sẽ gửi tất cả tin nhắn đang chờ xử lý đến thiết bị. Nếu thiết bị không bao giờ kết nối lại (ví dụ: nếu thiết bị được đặt lại về trạng thái ban đầu), thì thông báo sẽ hết thời gian chờ và bị loại bỏ khỏi bộ nhớ FCM. Thời gian chờ mặc định là 4 tuần, trừ phi bạn đặt cờ time_to_live.
Cách xem thêm thông tin chi tiết về việc gửi tin nhắn:
Để hiểu rõ hơn về việc gửi tin nhắn trên nền tảng Android hoặc Apple, hãy xem FCMbảng điều khiển báo cáo. Bảng điều khiển này ghi lại số lượng tin nhắn đã gửi và đã mở trên thiết bị Apple và Android, cùng với dữ liệu về "lượt hiển thị" (thông báo mà người dùng nhìn thấy) cho các ứng dụng Android.
Đối với các thiết bị Android đã bật tính năng nhắn tin trực tiếp qua kênh, nếu thiết bị không kết nối với FCM trong hơn một tháng, FCM vẫn chấp nhận tin nhắn nhưng sẽ loại bỏ ngay lập tức. Nếu thiết bị kết nối trong vòng 4 tuần kể từ tin nhắn dữ liệu gần đây nhất mà bạn đã gửi cho thiết bị đó, thì ứng dụng của bạn sẽ nhận được lệnh gọi lại onDeletedMessages(). Sau đó, ứng dụng có thể xử lý tình huống này một cách thích hợp, thường là bằng cách yêu cầu đồng bộ hoá toàn bộ từ máy chủ ứng dụng.
Cuối cùng, khi FCM cố gắng gửi một thông báo đến thiết bị và ứng dụng đã bị gỡ cài đặt, FCM sẽ loại bỏ thông báo đó ngay lập tức và vô hiệu hoá mã thông báo đăng ký. Các lần sau khi bạn cố gắng gửi tin nhắn đến thiết bị đó sẽ dẫn đến lỗi NotRegistered.
Thông tin xác thực
Tuỳ thuộc vào những tính năng FCM mà bạn triển khai, bạn có thể cần những thông tin đăng nhập sau đây từ dự án Firebase của mình:
| Mã dự án | Giá trị nhận dạng duy nhất cho dự án Firebase của bạn, được dùng trong các yêu cầu đến điểm cuối HTTP FCM v1. Giá trị này có trong ngăn Firebase console Settings (Cài đặt) của bạn. |
| Mã thông báo đăng ký | Một chuỗi mã thông báo duy nhất giúp xác định từng phiên bản ứng dụng khách. Bạn cần có mã thông báo đăng ký để gửi tin nhắn cho một thiết bị và nhóm thiết bị. Xin lưu ý rằng bạn phải giữ bí mật mã thông báo đăng ký. |
| Mã nhận dạng người gửi | Một giá trị bằng số duy nhất được tạo khi bạn tạo dự án Firebase, có trong thẻ Cloud Messaging của bảng điều khiển Firebase trong ngăn Cài đặt. Mã nhận dạng người gửi được dùng để xác định từng người gửi có thể gửi thông báo đến ứng dụng khách. |
| Mã truy cập | Mã thông báo OAuth 2.0 có thời hạn ngắn, cho phép các yêu cầu đến HTTP API phiên bản 1. Mã thông báo này được liên kết với một tài khoản dịch vụ thuộc dự án Firebase của bạn. Để tạo và xoay vòng mã truy cập, hãy làm theo các bước được mô tả trong phần Uỷ quyền yêu cầu gửi. |