Tài liệu này cung cấp tài liệu tham khảo về cú pháp XMPP dùng để truyền thông báo giữa máy chủ ứng dụng, ứng dụng khách và Firebase Cloud Messaging (FCM). Máy chủ ứng dụng của bạn phải kết nối với các điểm cuối sau:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
Các thông số có sẵn và tuỳ chọn được xếp vào các danh mục sau:
- Cú pháp thông báo hạ nguồn
- Mã phản hồi lỗi của thông báo hạ nguồn
- Cú pháp của thông báo luồng lên
- FCM thông báo kiểm soát
Cú pháp thông báo truyền xuống
Phần này cung cấp cú pháp để gửi thông báo truyền xuống.
Thông báo XMPP xuôi dòng (JSON)
Bảng sau đây liệt kê các mục tiêu, tuỳ chọn và tải trọng cho JSON XMPP tin nhắn.
Thông số | Cách sử dụng | Mô tả | |
---|---|---|---|
Mục tiêu | |||
to |
Chuỗi không bắt buộc |
Tham số này chỉ định người nhận tin nhắn.
Giá trị này có thể là mã thông báo đăng ký của thiết bị,
khoá thông báo hoặc một chủ đề duy nhất (có tiền tố là
|
|
condition |
Chuỗi không bắt buộc | 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 thông báo. Điều kiện được hỗ trợ: Chủ đề, có định dạng là ""yourTopics" trong chủ đề". Chiến dịch này không phân biệt chữ hoa chữ thường. Các toán tử được hỗ trợ: |
|
Lựa chọn | |||
message_id |
Bắt buộc, chuỗi | Tham số này xác định duy nhất một thông báo trong kết nối XMPP. |
|
collapse_key |
Chuỗi không bắt buộc | Thông số này xác định một nhóm thông báo (ví dụ: có
Chúng tôi không đảm bảo về thứ tự gửi thư. Lưu ý: Mỗi thời điểm chỉ được phép có tối đa 4 phím thu gọn khác nhau. Điều này có nghĩa là FCM có thể lưu trữ đồng thời 4 loại khác nhau tin nhắn trên mỗi ứng dụng khách. Nếu bạn vượt quá con số này, không thể đảm bảo rằng 4 khoá thu gọn FCM sẽ giữ nguyên. |
|
priority |
Chuỗi không bắt buộc | Đặt mức độ ưu tiên của thông báo. 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 thông số này tương ứng với mức độ ưu tiên của APN 5 và 10. Theo mặc định, tin nhắn thông báo được gửi với mức độ ưu tiên cao và tin nhắn dữ liệu được gửi với mức độ ưu tiên bình thường. Mức độ ưu tiên bình thường sẽ tối ưu hoá mức tiêu thụ pin và nên được sử dụng trừ phi cần giao hàng ngay. Đối với các thư có mức độ ưu tiên bình thường, ứng dụng có thể nhận thư bằng độ trễ không xác định. Khi thư được gửi với mức độ ưu tiên cao, thư đó sẽ được gửi ngay lập tức và ứng dụng có thể hiển thị thông báo. |
|
content_available |
Giá trị boolean | Trên các nền tảng của Apple, hãy dùng trường này để biểu thị |
|
mutable_content |
Giá trị boolean JSON không bắt buộc | Trên các nền tảng của Apple, hãy sử dụng trường này để biểu thị
|
|
time_to_live |
Số (không bắt buộc) | Tham số này chỉ định khoảng thời gian (tính bằng giây) tin nhắn sẽ được lưu giữ trong bộ nhớ FCM nếu thiết bị đang ngoại tuyến. Thời gian tối đa để phát trực tiếp đượ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 Thiết lập thời gian tồn tại của thông báo. |
|
dry_run |
Giá trị boolean | Khi bạn đặt tham số này thành Giá trị mặc định là |
|
Tải trọng | |||
data |
Đối tượng (không bắt buộc) | Tham số này chỉ định các cặp khoá-giá trị trong tải trọng của thông báo. Ví dụ: với Trên các nền tảng của Apple, nếu thông báo do APN gửi, thì thông báo đó sẽ đại diện cho các trường dữ liệu tuỳ chỉnh. Nếu
mặt hàng đó được phân phối chậm nhất vào FCM,
giá trị này được biểu thị dưới dạng từ điển khoá-giá trị trong Trên Android, việc này sẽ dẫn đến một ý định bổ sung có tên Khoá không được là một 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ư Bạn nên sử dụng các giá trị trong loại chuỗi. Bạn phải chuyển đổi giá trị trong các đối tượng hoặc các kiểu dữ liệu khác không phải chuỗi (ví dụ: số nguyên hoặc boolean) thành chuỗi. |
|
notification |
Đối tượng (không bắt buộc) | Tham số này chỉ định các cặp khoá-giá trị được xác định trước, hiển thị cho người dùng của
tải trọng thông báo. Hãy xem phần Hỗ trợ tải trọng thông báo để biết thông tin chi tiết. Thông tin khác
về các tuỳ chọn tin nhắn thông báo và tin nhắn dữ liệu, hãy xem
Loại thông báo. Nếu tải trọng thông báo được cung cấp hoặc
Đã đặt lựa chọn content_available thành true cho tin nhắn gửi đến Apple
thiết bị thì thông báo sẽ được gửi qua APN, nếu không thì tin nhắn sẽ được gửi qua
FCM.
|
Hỗ trợ tải trọng thông báo
Các bảng sau đây liệt kê các tuỳ chọn cài đặt được xác định trước các khoá dùng để tạo thông báo cho các nền tảng của Apple và Android.
Thông số | Cách sử dụng | Mô tả |
---|---|---|
title |
Chuỗi không bắt buộc |
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. |
body |
Chuỗi không bắt buộc |
Văn bản nội dung của thông báo. |
sound |
Chuỗi tùy chọn |
Âm thanh sẽ phát khi thiết bị nhận được thông báo.
Chuỗi chỉ định tệp âm thanh trong gói chính của ứng dụng khách hoặc trong
Thư mục |
badge |
Chuỗi tùy chọn |
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 |
click_action |
Chuỗi không bắt buộc |
Hành động liên quan đến lượt nhấp của người dùng vào thông báo.
Tương ứng với |
subtitle |
Chuỗi không bắt buộc |
Tiêu đề phụ của thông báo. |
body_loc_key |
Chuỗi không bắt buộc |
Khoá cho chuỗi nội dung trong tài nguyên chuỗi của ứng dụng để dùng để bản địa hoá văn bản nội dung theo nội dung bản địa hoá hiện tại của người dùng.
Tương ứng với Xem Tài liệu tham khảo 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 của bạn. |
body_loc_args |
Mảng JSON không bắt buộc dưới dạng chuỗi |
Các giá trị chuỗi biến sẽ được sử dụng thay cho thông số định dạng trong
Tương ứng với Xem Tài liệu tham khảo 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 của bạn. |
title_loc_key |
Chuỗi không bắt buộc |
Khoá cho chuỗi tiêu đề trong tài nguyên chuỗi của ứng dụng để dùng để bản địa hoá văn bản tiêu đề theo nội dung bản địa hoá hiện tại của người dùng.
Tương ứng với Xem Tài liệu tham khảo 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 của bạn. |
title_loc_args |
Mảng JSON không bắt buộc dưới dạng chuỗi |
Các giá trị chuỗi biến sẽ được sử dụng thay cho thông số định dạng trong
Tương ứng với Xem Tài liệu tham khảo 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 của bạn. |
Thông số | Cách sử dụng | Mô tả |
---|---|---|
title |
Chuỗi không bắt buộc |
Tiêu đề của thông báo. |
body |
Chuỗi không bắt buộc |
Văn bản nội dung của thông báo. |
android_channel_id |
Chuỗi không bắt buộc |
mã kênh của thông báo (mới trong Android O). Ứng dụng phải tạo một kênh bằng mã nhận dạng kênh này trước khi có bất kỳ thông báo nào có mã nhận dạng kênh này đã nhận được. Nếu bạn không gửi mã nhận dạng kênh này trong yêu cầu hoặc nếu mã nhận dạng kênh bạn cung cấp chưa được do ứng dụng tạo, FCM sẽ dùng mã nhận dạng kênh được chỉ định trong tệp kê khai ứng dụng. |
icon |
Chuỗi không bắt buộc |
Biểu tượng của thông báo.
Đặt biểu tượng thông báo thành |
sound |
Chuỗi không bắt buộc |
Âm thanh sẽ phát khi thiết bị nhận được thông báo.
Hỗ trợ |
tag |
Chuỗi không bắt buộc |
Giá trị nhận dạng được dùng để thay thế thông báo hiện có trong thông báo ngăn. 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à thông báo có cùng thẻ đang được thông báo mới sẽ thay thế thông báo hiện có trong ngăn thông báo. |
color |
Chuỗi không bắt buộc |
Màu biểu tượng của thông báo, được thể hiện ở định dạng |
click_action |
Chuỗi không bắt buộc |
Hành động liên quan đến 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ẽ khởi chạy khi người dùng nhấp vào thông báo. |
body_loc_key |
Chuỗi không bắt buộc |
Khoá cho chuỗi nội dung trong tài nguyên chuỗi của ứng dụng để dùng để bản địa hoá văn bản nội dung theo nội dung bản địa hoá hiện tại của người dùng. Xem Tài nguyên chuỗi để biết thêm thông tin. |
body_loc_args |
Mảng JSON không bắt buộc dưới dạng chuỗi |
Các giá trị chuỗi biến sẽ được sử dụng thay cho thông số định dạng trong
Xem Định dạng và định kiểu để biết thêm thông tin. |
title_loc_key |
Chuỗi không bắt buộc |
Khoá cho chuỗi tiêu đề trong tài nguyên chuỗi của ứng dụng để dùng để bản địa hoá văn bản tiêu đề theo nội dung bản địa hoá hiện tại của người dùng. Xem Tài nguyên chuỗi để biết thêm thông tin. |
title_loc_args |
Mảng JSON không bắt buộc dưới dạng chuỗi |
Các giá trị chuỗi biến sẽ được sử dụng thay cho thông số định dạng trong
Xem Định dạng và định kiểu để biết thêm thông tin. |
Thông số | Cách sử dụng | Mô tả |
---|---|---|
title |
Chuỗi không bắt buộc |
Tiêu đề của thông báo. |
body |
Chuỗi không bắt buộc |
Văn bản nội dung của thông báo. |
icon |
Chuỗi không bắt buộc |
URL sử dụng cho biểu tượng của thông báo. |
click_action |
Chuỗi không bắt buộc |
Hành động liên quan đến lượt nhấp của người dùng vào thông báo. Đối với tất cả giá trị URL, bạn phải sử dụng HTTPS. |
Diễn giải nội dung phản hồi tin nhắn XMPP xuôi dòng
Bảng sau đây liệt kê các trường xuất hiện trong phản hồi tin nhắn XMPP xuôi dòng.
Thông số | Cách sử dụng | Mô tả |
---|---|---|
from |
Bắt buộc, chuỗi | Tham số này chỉ định người đã gửi câu trả lời này. Giá trị là mã thông báo đăng ký của ứng dụng. |
message_id |
Bắt buộc, chuỗi | Tham số này xác định duy nhất một thông báo trong kết nối XMPP. Giá trị là một chuỗi xác định duy nhất thông báo liên quan. |
message_type |
Bắt buộc, chuỗi | Tham số này chỉ định một thông báo Nếu bạn đặt giá trị thành |
error |
Chuỗi không bắt buộc | Tham số này chỉ định một lỗi liên quan đến thông báo xuôi dòng. Giá trị này được đặt khi
message_type là nack . Xem bảng 4 để biết chi tiết. |
error_description |
Chuỗi tùy chọn | Tham số này cung cấp thông tin mô tả về lỗi. Đã đặt
khi message_type là nack . |
Mã phản hồi lỗi của tin nhắn xuôi dòng
Bảng sau đây liệt kê các mã phản hồi lỗi cho các thông báo thứ cấp.
Lỗi | Mã XMPP | Hành động được đề xuất |
---|---|---|
Thiếu mã thông báo đăng ký | INVALID_JSON |
Kiểm tra để đảm bảo yêu cầu có chứa mã thông báo đăng ký (trong
registration_id trong tin nhắn văn bản thuần tuý hoặc trong to
hoặc registration_ids trong JSON). |
Thông tin đăng ký APN không hợp lệ | INVALID_JSON |
Đối với các lượt đăng ký iOS, hãy kiểm tra để đảm bảo rằng yêu cầu đăng ký từ ứng dụng có chứa mã thông báo APN và mã ứng dụng hợp lệ. |
Mã thông báo đăng ký không hợp lệ | BAD_REGISTRATION |
Kiểm tra định dạng của mã thông báo đăng ký mà bạn chuyển đến máy chủ. Đảm bảo khớp với mã thông báo đăng ký mà ứng dụng khách nhận được khi đăng ký bằng FCM. Không nên cắt bớt hoặc thêm ký tự bổ sung. |
Thiết bị chưa được đăng ký | DEVICE_UNREGISTERED |
Mã thông báo đăng ký hiện có có thể hết hiệu lực trong một số trường hợp, bao gồm:
|
Người gửi không khớp | SENDER_ID_MISMATCH |
Mã thông báo đăng ký được liên kết với một nhóm người gửi nhất định. Khi một ứng dụng khách đăng ký đối với FCM, thì hệ thống phải chỉ định những người gửi được phép gửi thư. Bạn nên dùng một của những mã nhận dạng người gửi đó khi gửi thông báo đến ứng dụng. Nếu bạn chuyển sang một người gửi, mã thông báo đăng ký hiện có sẽ không hoạt động. |
JSON không hợp lệ | INVALID_JSON |
Kiểm tra để đảm bảo thông báo JSON được định dạng đúng và chứa các trường hợp lệ (ví dụ: đảm bảo truyền đúng loại dữ liệu). |
Tin nhắn quá lớn | INVALID_JSON |
Kiểm tra để đảm bảo rằng tổng kích thước của dữ liệu tải trọng có trong thông báo không vượt quá giới hạn FCM: 4096 byte đối với hầu hết thư hoặc 2048 byte đối với trường hợp thư đến chủ đề. Bao gồm cả các khoá và giá trị. |
Khoá dữ liệu không hợp lệ | INVALID_JSON |
Kiểm tra để đảm bảo rằng dữ liệu tải trọng không chứa khoá (chẳng hạn như from ,
gcm hoặc giá trị bất kỳ
có tiền tố google ) được FCM sử dụng nội bộ. Lưu ý rằng một số từ (chẳng hạn như collapse_key )
cũng được FCM sử dụng nhưng được phép trong tải trọng. Trong trường hợp đó,
giá trị tải trọng sẽ bị giá trị FCM ghi đè. |
Thời gian tồn tại không hợp lệ | INVALID_JSON |
Kiểm tra xem giá trị dùng trong time_to_live có phải là số nguyên đại diện cho
thời gian tính bằng giây trong khoảng từ 0 đến 2.419.200 (4 tuần). |
Thông báo ACK không hợp lệ | BAD_ACK |
Hãy kiểm tra để đảm bảo thông báo ack được định dạng đúng cách trước khi thử lại. Xem
bảng 6 để biết chi tiết. |
Hết giờ | SERVICE_UNAVAILABLE |
Máy chủ không thể xử lý yêu cầu kịp thời. Hãy thử yêu cầu lại, nhưng bạn phải:
Lưu ý: Những người gửi gây ra vấn đề sẽ có nguy cơ bị đưa vào danh sách đen. |
Lỗi máy chủ nội bộ | INTERNAL_SERVER_
|
Máy chủ đã gặp lỗi trong khi cố gắng xử lý yêu cầu. Bạn có thể thử lại yêu cầu tương tự theo các yêu cầu được liệt kê trong phần "Thời gian chờ" (xem hàng bên trên). |
Đã vượt quá tốc độ tin nhắn trên thiết bị | DEVICE_MESSAGE_RATE |
Tốc độ tin nhắn gửi đến một thiết bị cụ thể quá cao. Giảm số lượng tin nhắn đã gửi đến thiết bị này và không thử gửi lại ngay tới thiết bị này. |
Đã vượt quá tỷ lệ tin nhắn theo chủ đề | TOPICS_MESSAGE_RATE |
Tỷ lệ tin nhắn gửi đến người đăng ký một chủ đề cụ thể quá cao. Giảm số lượng thư đã gửi cho chủ đề này và không thử gửi lại ngay. |
Loại bỏ kết nối | CONNECTION_DRAINING |
Không thể xử lý thư vì kết nối đang cạn. Điều này xảy ra vì FCM cần đóng kết nối để thực hiện cân bằng tải. Thử gửi lại tin nhắn một kết nối XMPP khác. |
Thông tin đăng nhập APN không hợp lệ | INVALID_APNS_CREDENTIAL |
Không thể gửi tin nhắn nhắm đến một thiết bị iOS vì các APN bắt buộc khoá xác thực chưa được tải lên hoặc đã hết hạn. Kiểm tra tính hợp lệ của quá trình phát triển và thông tin xác thực sản xuất. |
Không xác thực được | AUTHENTICATION_FAILED |
Không xác thực được bằng các dịch vụ đẩy bên ngoài. Kiểm tra xem bạn có đang sử dụng chính xác chứng chỉ đẩy web. |
Cú pháp thông báo ngược dòng
Thông báo ngược dòng (upstream) là thông báo mà ứng dụng gửi đến máy chủ ứng dụng. Hiện tại, chỉ XMPP hỗ trợ chức năng nhắn tin ngược dòng. Xem tài liệu cho nền tảng của bạn để biết thêm thông tin về cách gửi tin nhắn từ ứng dụng khách.
Diễn giải thông báo XMPP ngược dòng
Bảng sau đây mô tả các trường trong thông báo XMPP được tạo của FCM để phản hồi các yêu cầu tin nhắn ngược dòng từ ứng dụng khách.
Thông số | Cách sử dụng | Mô tả |
---|---|---|
from |
Bắt buộc, chuỗi | Tham số này chỉ định người đã gửi tin nhắn. Giá trị là mã thông báo đăng ký của ứng dụng. |
category |
Bắt buộc, chuỗi | Tham số này chỉ định tên gói ứng dụng của ứng dụng khách đã gửi thông báo. |
message_id |
Bắt buộc, chuỗi | Tham số này chỉ định mã nhận dạng duy nhất của thông báo. |
data |
Chuỗi tùy chọn | Tham số này chỉ định các cặp khoá-giá trị trong tải trọng của thông báo. |
Đang gửi thông báo ACK
Bảng sau đây mô tả phản hồi ACK mà máy chủ ứng dụng dự kiến sẽ gửi đến FCM để phản hồi một thông báo ngược dòng mà máy chủ ứng dụng đã nhận được.
Thông số | Cách sử dụng | Mô tả |
---|---|---|
to |
Bắt buộc, chuỗi | Tham số này chỉ định người nhận tin nhắn phản hồi. Giá trị này phải là mã thông báo đăng ký của ứng dụng đã gửi thông báo ngược dòng. |
message_id |
Bắt buộc, chuỗi | Tham số này chỉ định xem tin nhắn trả lời sẽ dành cho thông báo nào. Giá trị phải là
giá trị message_id từ thông báo ngược dòng tương ứng. |
message_type |
Bắt buộc, chuỗi | Tham số này chỉ định một thông báo ack từ một máy chủ ứng dụng đến CCS.
Đối với các thông báo ngược dòng, bạn phải luôn đặt giá trị này thành ack . |
FCM thông báo từ máy chủ (XMPP)
Đây là thông báo được gửi từ FCM đến máy chủ ứng dụng. Sau đây là các loại thông báo chính mà FCM gửi đến máy chủ ứng dụng:
- Kiểm soát: Những thông báo do CCS tạo ra cho biết rằng hành động được yêu cầu từ máy chủ ứng dụng.
Bảng sau đây mô tả các trường có trong CCS của thông báo gửi đến máy chủ ứng dụng.
Thông số | Cách sử dụng | Mô tả |
---|---|---|
Trường chung | ||
message_type |
Bắt buộc, chuỗi | Tham số này chỉ định loại thông báo: control. Khi bạn đặt chính sách này thành |
control_type |
Chuỗi không bắt buộc | Tham số này chỉ định loại thông báo kiểm soát được gửi từ FCM. Hiện tại, chúng tôi chỉ hỗ trợ |