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