Khi sử dụng giao thức máy chủ ứng dụng FCM hoặc SDK dành cho quản trị viên Firebase, bạn có thể tạo yêu cầu thông báo và gửi chúng đến các loại mục tiêu sau:
- Tên chủ đề
- Điều kiện
- Mã thông báo đăng ký thiết bị
- Tên nhóm thiết bị (chỉ giao thức)
Bạn có thể gửi thông báo với tải trọng thông báo bao gồm các trường được xác định trước, tải trọng dữ liệu của các trường do người dùng xác định của riêng bạn hoặc một thông báo chứa cả hai loại tải trọng. Hãy xem phần Các loại thông báo để biết thêm thông tin.
Các ví dụ trên trang này cho thấy cách gửi thông báo bằng SDK dành cho quản trị viên của Firebase (hỗ trợ Node, Java, Python, C# và Go) cũng như giao thức HTTP v1. Ngoài ra, chúng tôi còn có hướng dẫn về cách gửi thông báo qua giao thức HTTP và phiên bản giao thức SAML cũ không còn được dùng nữa.
Gửi tin nhắn đến các thiết bị cụ thể
Để gửi đến một thiết bị cụ thể, hãy truyền mã thông báo đăng ký của thiết bị đó như minh hoạ. Xem thông tin thiết lập ứng dụng cho nền tảng của bạn để tìm hiểu thêm về mã thông báo đăng ký.
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';
const message = {
data: {
score: '850',
time: '2:45'
},
token: registrationToken
};
// Send a message to the device corresponding to the provided
// registration token.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// This registration token comes from the client FCM SDKs.
String registrationToken = "YOUR_REGISTRATION_TOKEN";
// See documentation on defining a message payload.
Message message = Message.builder()
.putData("score", "850")
.putData("time", "2:45")
.setToken(registrationToken)
.build();
// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# This registration token comes from the client FCM SDKs.
registration_token = 'YOUR_REGISTRATION_TOKEN'
# See documentation on defining a message payload.
message = messaging.Message(
data={
'score': '850',
'time': '2:45',
},
token=registration_token,
)
# Send a message to the device corresponding to the provided
# registration token.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Tiến hành
// Obtain a messaging.Client from the App.
ctx := context.Background()
client, err := app.Messaging(ctx)
if err != nil {
log.Fatalf("error getting Messaging client: %v\n", err)
}
// This registration token comes from the client FCM SDKs.
registrationToken := "YOUR_REGISTRATION_TOKEN"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Token: registrationToken,
}
// Send a message to the device corresponding to the provided
// registration token.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// This registration token comes from the client FCM SDKs.
var registrationToken = "YOUR_REGISTRATION_TOKEN";
// See documentation on defining a message payload.
var message = new Message()
{
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
Token = registrationToken,
};
// Send a message to the device corresponding to the provided
// registration token.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"notification":{
"title":"FCM Message",
"body":"This is an FCM Message"
},
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Sau khi thành công, mỗi phương thức gửi sẽ trả về một mã nhận dạng thư. SDK quản trị của Firebase trả về chuỗi mã nhận dạng ở định dạng projects/{project_id}/messages/{message_id}.
Phản hồi của giao thức HTTP là một khoá JSON duy nhất:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
Gửi tin nhắn đến nhiều thiết bị
API FCM dành cho quản trị viên cho phép bạn truyền nhiều tin nhắn tới danh sách mã thông báo đăng ký thiết bị. Bạn có thể chỉ định tối đa 500 mã thông báo đăng ký thiết bị cho mỗi lệnh gọi.
Node.js
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'YOUR_REGISTRATION_TOKEN_1',
// …
'YOUR_REGISTRATION_TOKEN_N',
];
const message = {
data: {score: '850', time: '2:45'},
tokens: registrationTokens,
};
getMessaging().sendMulticast(message)
.then((response) => {
console.log(response.successCount + ' messages were sent successfully');
});
Java
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
MulticastMessage message = MulticastMessage.builder()
.putData("score", "850")
.putData("time", "2:45")
.addAllTokens(registrationTokens)
.build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
Python
# Create a list containing up to 500 registration tokens.
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Tiến hành
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Giá trị trả về là một danh sách mã thông báo tương ứng với thứ tự của mã thông báo đầu vào. Điều này rất hữu ích khi bạn muốn kiểm tra xem mã thông báo nào dẫn đến lỗi.
Node.js
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'YOUR_REGISTRATION_TOKEN_1',
// …
'YOUR_REGISTRATION_TOKEN_N',
];
const message = {
data: {score: '850', time: '2:45'},
tokens: registrationTokens,
};
getMessaging().sendMulticast(message)
.then((response) => {
if (response.failureCount > 0) {
const failedTokens = [];
response.responses.forEach((resp, idx) => {
if (!resp.success) {
failedTokens.push(registrationTokens[idx]);
}
});
console.log('List of tokens that caused failures: ' + failedTokens);
}
});
Java
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
MulticastMessage message = MulticastMessage.builder()
.putData("score", "850")
.putData("time", "2:45")
.addAllTokens(registrationTokens)
.build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
List<SendResponse> responses = response.getResponses();
List<String> failedTokens = new ArrayList<>();
for (int i = 0; i < responses.size(); i++) {
if (!responses.get(i).isSuccessful()) {
// The order of responses corresponds to the order of the registration tokens.
failedTokens.add(registrationTokens.get(i));
}
}
System.out.println("List of tokens that caused failures: " + failedTokens);
}
Python
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
if response.failure_count > 0:
responses = response.responses
failed_tokens = []
for idx, resp in enumerate(responses):
if not resp.success:
# The order of responses corresponds to the order of the registration tokens.
failed_tokens.append(registration_tokens[idx])
print('List of tokens that caused failures: {0}'.format(failed_tokens))
Tiến hành
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
if br.FailureCount > 0 {
var failedTokens []string
for idx, resp := range br.Responses {
if !resp.Success {
// The order of responses corresponds to the order of the registration tokens.
failedTokens = append(failedTokens, registrationTokens[idx])
}
}
fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}
C#
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
var failedTokens = new List<string>();
for (var i = 0; i < response.Responses.Count; i++)
{
if (!response.Responses[i].IsSuccess)
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens.Add(registrationTokens[i]);
}
}
Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}
Gửi tin nhắn đến các chủ đề
Sau khi đã tạo một chủ đề, bạn có thể gửi thông báo đến chủ đề bằng cách đăng ký các bản sao ứng dụng khách cho chủ đề đó ở phía máy khách hoặc thông qua API máy chủ. Nếu đây là lần đầu tiên bạn tạo yêu cầu gửi cho FCM, hãy xem hướng dẫn về môi trường máy chủ và FCM để biết thông tin cơ bản và thông tin thiết lập quan trọng.
Trong logic gửi trên phần phụ trợ, hãy chỉ định tên chủ đề mong muốn như sau:
Node.js
// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';
const message = {
data: {
score: '850',
time: '2:45'
},
topic: topic
};
// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";
// See documentation on defining a message payload.
Message message = Message.builder()
.putData("score", "850")
.putData("time", "2:45")
.setTopic(topic)
.build();
// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'
# See documentation on defining a message payload.
message = messaging.Message(
data={
'score': '850',
'time': '2:45',
},
topic=topic,
)
# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Tiến hành
// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Topic: topic,
}
// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";
// See documentation on defining a message payload.
var message = new Message()
{
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
Topic = topic,
};
// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
}
}
}
cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message": {
"topic" : "foo-bar",
"notification": {
"body": "This is a Firebase Cloud Messaging Topic Message!",
"title": "FCM Message"
}
}
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Để gửi thông báo đến một tổ hợp chủ đề, hãy chỉ định điều kiện. Đây là biểu thức boolean chỉ định các chủ đề mục tiêu. Ví dụ: điều kiện sau đây sẽ gửi thông báo đến các thiết bị đã đăng ký TopicA và TopicB hoặc TopicC:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
Trước tiên, FCM sẽ đánh giá mọi điều kiện trong dấu ngoặc đơn, sau đó đánh giá biểu thức từ trái sang phải. Trong biểu thức trên, người dùng đã đăng ký theo dõi bất kỳ chủ đề nào sẽ không nhận được thông báo. Tương tự, người dùng không đăng ký TopicA sẽ không nhận được thông báo. Những cách kết hợp sau đây nhận được:
TopicAvàTopicBTopicAvàTopicC
Bạn có thể thêm tối đa 5 chủ đề vào biểu thức có điều kiện.
Để gửi đến một điều kiện:
Node.js
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';
// See documentation on defining a message payload.
const message = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
condition: condition
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";
// See documentation on defining a message payload.
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.setCondition(condition)
.build();
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"
# See documentation on defining a message payload.
message = messaging.Message(
notification=messaging.Notification(
title='$GOOG up 1.43% on the day',
body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
),
condition=condition,
)
# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Tiến hành
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Condition: condition,
}
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";
// See documentation on defining a message payload.
var message = new Message()
{
Notification = new Notification()
{
Title = "$GOOG up 1.43% on the day",
Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
},
Condition = condition,
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"condition": "'dogs' in topics || 'cats' in topics",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message",
}
}
}
cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"notification": {
"title": "FCM Message",
"body": "This is a Firebase Cloud Messaging Topic Message!",
},
"condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Gửi tin nhắn đến các nhóm thiết bị
Để gửi thông báo đến các nhóm thiết bị, hãy sử dụng API HTTP v1. Nếu bạn hiện đang gửi đến các nhóm thiết bị bằng cách sử dụng API gửi phiên bản cũ không dùng nữa cho giao thức HTTP hoặc phiên hỗ trợ RCS hoặc bất kỳ phiên bản cũ nào của SDK quản trị của Firebase dành cho Node.js dựa trên giao thức cũ, bạn nên di chuyển sang API HTTP v1 trong thời gian sớm nhất có thể. API gửi cũ sẽ bị vô hiệu hoá và xoá vào tháng 6 năm 2024.
Việc gửi thông báo đến một nhóm thiết bị rất giống với việc gửi thông báo đến một thiết bị riêng lẻ, sử dụng cùng một phương thức để uỷ quyền gửi yêu cầu. Đặt trường token thành khoá thông báo nhóm:
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
}
}
}
lệnh cURL
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
},
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Gửi một loạt thư
SDK dành cho quản trị viên hỗ trợ gửi thư hàng loạt. Bạn có thể nhóm tối đa 500 thông báo vào một lô và gửi tất cả các thông báo đó trong một lệnh gọi API duy nhất, với sự cải thiện đáng kể về hiệu suất so với việc gửi các yêu cầu HTTP riêng biệt cho từng thông báo.
Bạn có thể dùng tính năng này để tạo một nhóm thông báo tuỳ chỉnh và gửi đến nhiều người nhận, bao gồm cả chủ đề hoặc mã thông báo đăng ký thiết bị cụ thể. Chẳng hạn, hãy sử dụng tính năng này khi bạn cần gửi đồng thời thông báo đến nhiều đối tượng với thông tin chi tiết hơi khác nhau trong nội dung thông báo.
Node.js
// Create a list containing up to 500 messages.
const messages = [];
messages.push({
notification: { title: 'Price drop', body: '5% off all electronics' },
token: registrationToken,
});
messages.push({
notification: { title: 'Price drop', body: '2% off all books' },
topic: 'readers-club',
});
getMessaging().sendAll(messages)
.then((response) => {
console.log(response.successCount + ' messages were sent successfully');
});
Java
// Create a list containing up to 500 messages.
List<Message> messages = Arrays.asList(
Message.builder()
.setNotification(Notification.builder()
.setTitle("Price drop")
.setBody("5% off all electronics")
.build())
.setToken(registrationToken)
.build(),
// ...
Message.builder()
.setNotification(Notification.builder()
.setTitle("Price drop")
.setBody("2% off all books")
.build())
.setTopic("readers-club")
.build()
);
BatchResponse response = FirebaseMessaging.getInstance().sendAll(messages);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
Python
# Create a list containing up to 500 messages.
messages = [
messaging.Message(
notification=messaging.Notification('Price drop', '5% off all electronics'),
token=registration_token,
),
# ...
messaging.Message(
notification=messaging.Notification('Price drop', '2% off all books'),
topic='readers-club',
),
]
response = messaging.send_all(messages)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Tiến hành
// Create a list containing up to 500 messages.
messages := []*messaging.Message{
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "5% off all electronics",
},
Token: registrationToken,
},
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "2% off all books",
},
Topic: "readers-club",
},
}
br, err := client.SendAll(context.Background(), messages)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "5% off all electronics",
},
Token = registrationToken,
},
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "2% off all books",
},
Topic = "readers-club",
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
Gửi tin nhắn đã bật tính năng khởi động trực tiếp (chỉ dành cho Android)
Bạn có thể gửi thông báo đến thiết bị ở chế độ khởi động trực tiếp bằng HTTP v1 hoặc API HTTP cũ. Trước khi gửi tới các thiết bị ở chế độ khởi động trực tiếp, hãy đảm bảo bạn đã hoàn thành các bước để cho phép thiết bị ứng dụng nhận thông báo FCM ở chế độ khởi động trực tiếp.
Gửi bằng API HTTP FCM v1
Yêu cầu thông báo phải bao gồm khoá "direct_boot_ok" : true trong các tuỳ chọn AndroidConfig của nội dung yêu cầu. Ví dụ:
https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
"data": {
"score": "5x1",
"time": "15:10"
},
"android": {
"direct_boot_ok": true,
},
}
Gửi bằng API HTTP cũ của FCM
Yêu cầu thông báo phải bao gồm khoá "direct_boot_ok" : true ở cấp cao nhất của nội dung yêu cầu. Ví dụ:
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
"direct_boot_ok" : true
}
Các ứng dụng trên các thiết bị hiện đang ở chế độ khởi động trực tiếp (và cả khi không ở chế độ đó) có thể xử lý tin nhắn được gửi bằng khoá này trong nội dung yêu cầu.
Tuỳ chỉnh thông báo trên nhiều nền tảng
Cả SDK quản trị của Firebase và giao thức HTTP FCM v1 đều cho phép các yêu cầu thông báo của bạn đặt tất cả các trường có sẵn trong đối tượng message. Chẳng hạn như:
- một tập hợp các trường phổ biến sẽ được tất cả thực thể ứng dụng nhận thông báo 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 diễn giải bởi các thực thể ứng dụng chạy trên nền tảng đã chỉ định.
Quy tắc chặn dành riêng cho nền tảng cho phé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ý chính xác 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 phổ biến
Hãy sử dụng các trường phổ biến khi bạn:
- Nhắm mục tiêu 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 tin nhắn đến chủ đề
Mọi 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 phổ biến sau đây:
Thời điểm sử dụng các trường dành riêng cho nền tảng
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
- Gửi các trường dành riêng cho nền tảng ngoài các trường phổ biến
Mỗi khi bạn chỉ muốn gửi giá trị đến một số nền tảng cụ thể, 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 và web của Apple 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 cho Apple và một cho web.
Khi bạn gửi tin nhắn bằng các tuỳ chọn gửi cụ thể, hãy sử dụng các trường dành riêng cho nền tảng để đặt các tin nhắn đó. Nếu muốn, bạn có thể chỉ định các giá trị khác nhau cho mỗi nền tảng. Tuy nhiên, ngay cả khi muốn đặt cùng một giá trị về cơ bản 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ị 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, giá trị này được đặt là ngày hết hạn.
Ví dụ: tin nhắn thông báo với các lựa chọn về màu sắc và biểu tượng
Ví dụ này sẽ gửi yêu cầu gửi một 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ố cơ chế ghi đè dành riêng cho nền tảng đến các thiết bị Android.
Đối với Android, yêu cầu này sẽ đặt một biểu tượng và màu đặc biệt để hiển thị trên thiết bị Android. Như đã lưu ý trong tài liệu tham khảo cho AndroidNotification, màu được chỉ định ở định dạng #rrggbb và hình ảnh phải là tài nguyên biểu tượng có thể vẽ cục bộ cho ứng dụng Android.
Dưới đây là số liệu ước tính về hiệu ứng hình ảnh trên thiết bị của người dùng:
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: '`$FooCorp` up 1.43% on the day',
body: 'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
android: {
notification: {
icon: 'stock_ticker_update',
color: '#7e55c3'
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.setAndroidConfig(AndroidConfig.builder()
.setTtl(3600 * 1000)
.setNotification(AndroidNotification.builder()
.setIcon("stock_ticker_update")
.setColor("#f45342")
.build())
.build())
.setApnsConfig(ApnsConfig.builder()
.setAps(Aps.builder()
.setBadge(42)
.build())
.build())
.setTopic("industry-tech")
.build();
Python
message = messaging.Message(
notification=messaging.Notification(
title='$GOOG up 1.43% on the day',
body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
),
android=messaging.AndroidConfig(
ttl=datetime.timedelta(seconds=3600),
priority='normal',
notification=messaging.AndroidNotification(
icon='stock_ticker_update',
color='#f45342'
),
),
apns=messaging.APNSConfig(
payload=messaging.APNSPayload(
aps=messaging.Aps(badge=42),
),
),
topic='industry-tech',
)
Tiến hành
oneHour := time.Duration(1) * time.Hour
badge := 42
message := &messaging.Message{
Notification: &messaging.Notification{
Title: "$GOOG up 1.43% on the day",
Body: "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
},
Android: &messaging.AndroidConfig{
TTL: &oneHour,
Notification: &messaging.AndroidNotification{
Icon: "stock_ticker_update",
Color: "#f45342",
},
},
APNS: &messaging.APNSConfig{
Payload: &messaging.APNSPayload{
Aps: &messaging.Aps{
Badge: &badge,
},
},
},
Topic: "industry-tech",
}
C#
var message = new Message
{
Notification = new Notification()
{
Title = "$GOOG up 1.43% on the day",
Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
},
Android = new AndroidConfig()
{
TimeToLive = TimeSpan.FromHours(1),
Notification = new AndroidNotification()
{
Icon = "stock_ticker_update",
Color = "#f45342",
},
},
Apns = new ApnsConfig()
{
Aps = new Aps()
{
Badge = 42,
},
},
Topic = "industry-tech",
};
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":"`$FooCorp` up 1.43% on the day",
"body":"FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
},
"android":{
"notification":{
"icon":"stock_ticker_update",
"color":"#7e55c3"
}
}
}
}
Hãy xem tài liệu tham khảo về HTTP v1 để biết đầy đủ thông tin chi tiết về các khoá có trong khối dành riêng cho từng nền tảng trong nội dung thông báo.
Ví dụ: tin nhắn thông báo có hình ảnh tuỳ chỉnh
Trong ví dụ sau đây, yêu cầu gửi sẽ gửi một tiêu đề thông báo chung đến tất cả các nền tảng, nhưng cũng gửi một hình ảnh. Dưới đây là số liệu ước tính về hiệu ứng hình ảnh trên thiết bị của người dùng:
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: 'Sparky says hello!'
},
android: {
notification: {
imageUrl: 'https://foo.bar.pizza-monster.png'
}
},
apns: {
payload: {
aps: {
'mutable-content': 1
}
},
fcm_options: {
image: 'https://foo.bar.pizza-monster.png'
}
},
webpush: {
headers: {
image: 'https://foo.bar.pizza-monster.png'
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":"Sparky says hello!",
},
"android":{
"notification":{
"image":"https://foo.bar/pizza-monster.png"
}
},
"apns":{
"payload":{
"aps":{
"mutable-content":1
}
},
"fcm_options": {
"image":"https://foo.bar/pizza-monster.png"
}
},
"webpush":{
"headers":{
"image":"https://foo.bar/pizza-monster.png"
}
}
}
}
Hãy xem tài liệu tham khảo về HTTP v1 để biết đầy đủ thông tin chi tiết về các khoá có trong khối dành riêng cho từng nền tảng trong nội dung thông báo.
Ví dụ: thông báo về hành động nhấp chuột liên quan
Ví dụ sau đây gửi yêu cầu gửi một tiêu đề thông báo chung đến tất cả các nền tảng, nhưng cũng gửi một thao tác để ứng dụng thực hiện để phản hồi khi người dùng tương tác với thông báo. Dưới đây là số liệu ước tính về hiệu ứng hình ảnh trên thiết bị của người dùng:
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: 'Breaking News....'
},
android: {
notification: {
clickAction: 'news_intent'
}
},
apns: {
payload: {
aps: {
'category': 'INVITE_CATEGORY'
}
}
},
webpush: {
fcmOptions: {
link: 'breakingnews.html'
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":"Breaking News...",
},
"android":{
"notification":{
"click_action":"news_intent"
}
},
"apns":{
"payload":{
"aps":{
"category" : "INVITE_CATEGORY"
}
},
},
"webpush":{
"fcm_options":{
"link":"breakingnews.html"
}
}
}
}
Hãy xem tài liệu tham khảo về HTTP v1 để biết đầy đủ thông tin chi tiết về các khoá có trong khối dành riêng cho từng nền tảng trong nội dung thông báo.
Ví dụ: tin nhắn thông báo có các tuỳ chọn bản địa hoá
Trong ví dụ sau đây, yêu cầu gửi sẽ gửi các tuỳ chọn bản địa hoá để ứng dụng cho thấy thông báo đã bản địa hoá. Dưới đây là số liệu ước tính về hiệu ứng hình ảnh trên thiết bị của người dùng:
Node.js
var topicName = 'industry-tech';
var message = {
android: {
ttl: 3600000,
notification: {
bodyLocKey: 'STOCK_NOTIFICATION_BODY',
bodyLocArgs: ['FooCorp', '11.80', '835.67', '1.43']
}
},
apns: {
payload: {
aps: {
alert: {
locKey: 'STOCK_NOTIFICATION_BODY',
locArgs: ['FooCorp', '11.80', '835.67', '1.43']
}
}
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Kiến trúc chuyển trạng thái đại diện (REST)
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"Tech",
"android":{
"ttl":"3600s",
"notification":{
"body_loc_key": "STOCK_NOTIFICATION_BODY",
"body_loc_args": ["FooCorp", "11.80", "835.67", "1.43"],
},
},
"apns":{
"payload":{
"aps":{
"alert" : {
"loc-key": "STOCK_NOTIFICATION_BODY",
"loc-args": ["FooCorp", "11.80", "835.67", "1.43"],
},
},
},
},
},
}'
Hãy xem tài liệu tham khảo về HTTP v1 để biết đầy đủ thông tin chi tiết về các khoá có trong khối dành riêng cho từng nền tảng trong nội dung thông báo.
Mã lỗi REST cho API HTTP v1
Phản hồi lỗi HTTP cho API HTTP v1 chứa mã lỗi, thông báo lỗi và trạng thái lỗi.
Chúng cũng có thể chứa một mảng details với thông tin chi tiết khác về lỗi.
Dưới đây là hai phản hồi lỗi mẫu:
Ví dụ 1: Phản hồi lỗi từ yêu cầu API HTTP v1 có giá trị không hợp lệ trong một thông báo dữ liệu
{
"error": {
"code": 400,
"message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "message.data[0].value",
"description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
}
]
}
]
}
}
Ví dụ 2: Phản hồi lỗi từ yêu cầu API HTTP v1 có mã thông báo đăng ký không hợp lệ
{
"error": {
"code": 400,
"message": "The registration token is not a valid FCM registration token",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
"errorCode": "INVALID_ARGUMENT"
}
]
}
}
Lưu ý rằng cả hai thông báo đều có cùng mã và trạng thái, nhưng mảng chi tiết chứa giá trị thuộc các loại khác nhau. Ví dụ đầu tiên có loại type.googleapis.com/google.rpc.BadRequest chỉ ra có lỗi trong giá trị yêu cầu. Ví dụ thứ hai với loại type.googleapis.com/google.firebase.fcm.v1.FcmError có lỗi cụ thể về FCM. Đối với nhiều lỗi, mảng chi tiết chứa thông tin mà bạn cần để gỡ lỗi và tìm giải pháp.
Bảng sau đây liệt kê các mã lỗi API FCM v1 REST và nội dung mô tả tương ứng.
| Mã lỗi | Các bước mô tả và giải quyết |
|---|---|
UNSPECIFIED_ERROR Không có thêm thông tin nào về lỗi này. |
Không có. |
INVALID_ARGUMENT (Mã lỗi HTTP = 400) Tham số yêu cầu không hợp lệ. Phần mở rộng thuộc loại google.rpc.BadRequest được trả về để chỉ định trường nào không hợp lệ. |
Các nguyên nhân có thể là do đăng ký không hợp lệ, tên gói không hợp lệ, thông báo quá lớn, khoá dữ liệu không hợp lệ, TTL không hợp lệ hoặc các thông số không hợp lệ khác. Đăng ký không hợp lệ: Hãy 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 mã này 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. Đừng cắt bớt mã thông báo hoặc thêm các ký tự bổ sung. Tên gói không hợp lệ: Đảm bảo rằng thông báo được gửi tới một mã thông báo đăng ký có tên gói khớp với giá trị được truyền trong yêu cầu. Thư quá lớn: Kiểm tra để đảm bảo rằng tổng kích thước của dữ liệu tải trọng trong một tin nhắn không vượt quá giới hạn của FCM: 4096 byte đối với hầu hết các tin nhắn hoặc 2048 byte đối với tin nhắn đến chủ đề. Điều này bao gồm cả khoá và giá trị. Khoá dữ liệu không hợp lệ: 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 hoặc gcm hoặc bất kỳ giá trị nào có tiền tố google) mà FCM sử dụng nội bộ. Lưu ý rằng một số từ (chẳng hạn như coll_key) cũng được FCM sử dụng nhưng được cho phép trong tải trọng. Trong trường hợp đó, giá trị tải trọng sẽ bị giá trị FCM ghi đè. TTL không hợp lệ: Kiểm tra để đảm bảo rằng giá trị dùng trong ttl là một số nguyên đại diện cho khoảng thời gian tính bằng giây, từ 0 đến 2.419.200 (4 tuần). Tham số không hợp lệ: Kiểm tra để đảm bảo rằng các tham số đã cung cấp có tên và loại chính xác. |
UNREGISTERED (Mã lỗi HTTP = 404) Phiên bản ứng dụng đã bị huỷ đăng ký khỏi FCM. Điều này thường có nghĩa là mã thông báo được sử dụng không còn hợp lệ và bạn phải sử dụng mã mới. |
Lỗi này có thể xảy ra do thiếu mã thông báo đăng ký hoặc mã thông báo chưa đăng ký. Thiếu thông tin đăng ký: Nếu mục tiêu của thông báo là giá trị token, hãy kiểm tra để đảm bảo yêu cầu có chứa mã thông báo đăng ký.Chưa đăng ký: Mã thông báo đăng ký hiện có có thể không hợp lệ trong một số trường hợp, bao gồm: – 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 của APN báo cáo mã thông báo APN 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 APN đã 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 không được định cấu hình để nhận thông báo. Đối với tất cả những trường hợp này, hãy xoá mã thông báo đăng ký này khỏi máy chủ ứng dụng và ngừng sử dụng mã này để gửi tin nhắn. |
SENDER_ID_MISMATCH (Mã lỗi HTTP = 403) Mã người gửi được xác thực khác với mã người gửi của mã thông báo đăng ký. |
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 ứng dụng khách đăng ký FCM, ứng dụng khách phải chỉ định người gửi nào được phép gửi thư. Bạn nên sử dụng một trong các mã nhận dạng 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 có sẽ không hoạt động. |
QUOTA_EXCEEDED (Mã lỗi HTTP = 429) Đã vượt quá giới hạn gửi đối với mục tiêu thông báo. Phần mở rộng thuộc loại google.rpc.QuotaFailure được trả về để chỉ định hạn mức nào đã vượt quá. |
Lỗi này có thể xảy ra do vượt quá hạn mức tốc độ tin nhắn, vượt quá hạn mức tốc độ tin nhắn trên thiết bị hoặc vượt quá hạn mức tốc độ tin nhắn theo chủ đề. Đã vượt quá tốc độ tin nhắn: Tốc độ gửi tin nhắn quá cao. Bạn phải giảm tổng tần suất gửi tin nhắn. Sử dụng thuật toán thời gian đợi luỹ thừa với độ trễ ban đầu tối thiểu là 1 phút để thử lại các thông báo bị từ chối. Đã vượt quá tỷ lệ tin nhắn trên thiết bị: Tỷ lệ tin nhắn đến một thiết bị cụ thể quá cao. Xem giới hạn số lượng tin nhắn cho một thiết bị. Hãy giảm số lượng tin nhắn gửi đến thiết bị này và dùng thuật toán thời gian đợi luỹ thừa để thử gửi lại. Đã vượt quá tỷ lệ tin nhắn theo chủ đề: Tỷ lệ tin nhắn gửi đến người đăng ký một chủ đề cụ thể quá cao. Hãy giảm số lượng tin nhắn được gửi cho chủ đề này và sử dụng thời gian đợi luỹ thừa với độ trễ ban đầu tối thiểu là 1 phút để thử gửi lại. |
UNAVAILABLE (Mã lỗi HTTP = 503) Máy chủ bị quá tải. |
Máy chủ không thể xử lý yêu cầu kịp thời. Thử gửi lại cùng một yêu cầu, nhưng bạn phải: – Thực hiện tiêu đề Thử lại sau nếu tiêu đề đó có trong phản hồi từ Máy chủ kết nối FCM. – Triển khai 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 lần thử đầu tiên, hãy chờ ít nhất 2 giây trước lần thử tiếp theo, sau đó 4 giây, v.v.). Nếu bạn đang gửi nhiều thư, hãy xem xét việc áp dụng chế độ rung. Để biết thêm thông tin, hãy xem phần Xử lý lần thử lại. Những người gửi gây ra sự cố có nguy cơ sẽ bị đưa vào danh sách từ chối. |
INTERNAL (Mã lỗi HTTP = 500) Đã xảy ra lỗi nội bộ không xác định. |
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 chính yêu cầu đó theo các đề xuất trong phần Xử lý lần thử lại. Nếu lỗi vẫn tiếp diễn, vui lòng liên hệ với bộ phận hỗ trợ của Firebase. |
THIRD_PARTY_AUTH_ERROR (mã lỗi HTTP = 401) Chứng chỉ APN hoặc khoá xác thực đẩy trên web không hợp lệ hoặc bị thiếu. |
Không thể gửi thư nhắm mục tiêu đến thiết bị iOS hoặc đăng ký đẩy trên web. Kiểm tra tính hợp lệ của thông tin đăng nhập vào quá trình phát triển và phát hành công khai. |
Mã lỗi quản trị
Bảng sau đây liệt kê các mã lỗi API FCM dành cho Quản trị viên Firebase và nội dung mô tả các mã đó, bao gồm cả các bước giải quyết được đề xuất.
| Mã lỗi | Các bước mô tả và giải quyết |
|---|---|
messaging/invalid-argument |
Đối số không hợp lệ đã được cung cấp cho phương thức FCM. Thông báo lỗi phải chứa thông tin bổ sung. |
messaging/invalid-recipient |
Người nhận thư bạn muốn không hợp lệ. Thông báo lỗi phải chứa thông tin bổ sung. |
messaging/invalid-payload |
Đã cung cấp đối tượng tải trọng thông báo không hợp lệ. Thông báo lỗi phải chứa thông tin bổ sung. |
messaging/invalid-data-payload-key |
Tải trọng thông báo dữ liệu chứa khoá không hợp lệ. Xem tài liệu tham khảo về
DataMessagePayload để biết các khoá bị hạn chế.
|
messaging/payload-size-limit-exceeded |
Tải trọng tin nhắn đã cung cấp vượt quá giới hạn kích thước FCM. Giới hạn là 4096 byte đối với hầu hết các thông báo. Đối với các thư được gửi đến chủ đề, giới hạn là 2048 byte. Tổng kích thước tải trọng bao gồm cả khoá và giá trị. |
messaging/invalid-options |
Bạn đã cung cấp một đối tượng tuỳ chọn thông báo không hợp lệ. Thông báo lỗi phải chứa thông tin bổ sung. |
messaging/invalid-registration-token |
Bạn đã cung cấp mã thông báo đăng ký không hợp lệ. Đảm bảo mã này khớp với mã thông báo đăng ký mà ứng dụng nhận được khi đăng ký bằng FCM. Đừng cắt bớt hoặc thêm các ký tự khác vào văn bản đó. |
messaging/registration-token-not-registered |
Mã thông báo đăng ký đã cung cấp chưa được đăng ký. Một mã thông báo đăng ký đã từng hợp lệ có thể bị huỷ đăng ký vì nhiều lý do, trong đó có:
|
messaging/invalid-package-name |
Thông báo được gửi tới một mã thông báo đăng ký có tên gói không khớp với lựa chọn
restrictedPackageName đã cung cấp.
|
messaging/message-rate-exceeded |
Tỷ lệ tin nhắn đến một mục tiêu cụ thể quá cao. Giảm số lượng tin nhắn được gửi đến thiết bị hoặc chủ đề này và không thử gửi lại ngay lập tức đến mục tiêu này. |
messaging/device-message-rate-exceeded |
Tốc độ tin nhắn đế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 lập tức đến thiết bị này. |
messaging/topics-message-rate-exceeded |
Tỷ lệ tin nhắn đến người đăng ký tới 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 chủ đề này ngay lập tức. |
messaging/too-many-topics |
Một mã thông báo đăng ký đã đăng ký với số lượng chủ đề tối đa và không thể đăng ký thêm nữa. |
messaging/invalid-apns-credentials |
Không thể gửi một thông báo nhắm đến một thiết bị Apple vì chứng chỉ SSL bắt buộc của APN chưa được tải lên hoặc đã hết hạn. Kiểm tra tính hợp lệ của các chứng chỉ phát triển và phát hành công khai. |
messaging/mismatched-credential |
Thông tin đăng nhập dùng để xác thực SDK này không có quyền gửi thông báo tới thiết bị tương ứng với mã thông báo đăng ký được cung cấp. Hãy đảm bảo cả thông tin đăng nhập và mã thông báo đăng ký đều thuộc về cùng một dự án Firebase. Xem bài viết Thêm Firebase vào ứng dụng của bạn để tham khảo tài liệu về cách xác thực SDK quản trị của Firebase. |
messaging/authentication-error |
SDK không thể xác thực với máy chủ FCM. Hãy đảm bảo bạn xác thực SDK quản trị Firebase bằng thông tin xác thực có quyền thích hợp để gửi thông báo FCM. Xem bài viết Thêm Firebase vào ứng dụng của bạn để tham khảo tài liệu về cách xác thực SDK quản trị của Firebase. |
messaging/server-unavailable |
Máy chủ FCM không thể xử lý yêu cầu kịp thời. Bạn nên
thử lại yêu cầu tương tự, nhưng phải:
|
messaging/internal-error |
Máy chủ FCM đã gặp lỗi trong khi cố gắng xử lý yêu cầu. Bạn có thể thử lại cùng một yêu cầu theo các yêu cầu nêu trong hàng messaging/server-unavailable ở trên. Nếu
lỗi vẫn tiếp diễn, vui lòng báo cáo sự cố với kênh hỗ trợ
Báo cáo lỗi của chúng tôi.
|
messaging/unknown-error |
Đã trả về lỗi máy chủ không xác định. Hãy xem phản hồi của máy chủ thô trong thông báo lỗi để biết thêm chi tiết. Nếu bạn gặp lỗi này, vui lòng báo cáo toàn bộ thông báo lỗi đó cho kênh hỗ trợ về Báo cáo lỗi của chúng tôi. |
Gửi thông báo bằng giao thức máy chủ ứng dụng cũ
Nếu bạn đang sử dụng các giao thức cũ, hãy tạo các yêu cầu thông báo như trình bày trong phần này. Xin lưu ý rằng nếu bạn đang gửi đến nhiều nền tảng qua HTTP, giao thức v1 có thể đơn giản hoá đáng kể các yêu cầu thông báo của bạn.
Gửi tin nhắn đến các thiết bị cụ thể
Để gửi thông báo đến các thiết bị cụ thể, hãy đặt khoá to thành mã thông báo đăng ký cho phiên bản ứng dụng cụ thể. Xem thông tin thiết lập ứng dụng cho nền tảng của bạn để tìm hiểu thêm về mã thông báo đăng ký.
Yêu cầu POST qua HTTP
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
phản hồi HTTP
{ "multicast_id": 108,
"success": 1,
"failure": 0,
"results": [
{ "message_id": "1:08" }
]
}
Thông báo UPI
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
Phản hồi SAML
<message id="">
<gcm xmlns="google:mobile:data">
{
"from":"REGID",
"message_id":"m-1366082849205"
"message_type":"ack"
}
</gcm>
</message>
Máy chủ kết nối WebRTC cung cấp một số tuỳ chọn khác cho phản hồi. Hãy xem phần Định dạng phản hồi của máy chủ.
Để biết danh sách đầy đủ các tuỳ chọn thông báo có sẵn khi gửi thông báo xuôi dòng đến các ứng dụng khách, hãy xem thông tin tham chiếu cho giao thức máy chủ kết nối mà bạn đã chọn, HTTP hoặc XMPP.
Gửi tin nhắn đến các chủ đề
Việc gửi tin nhắn tới một chủ đề Giải pháp gửi thông báo qua đám mây của Firebase rất giống với việc gửi thông báo cho một thiết bị riêng lẻ hoặc cho một nhóm người dùng. Máy chủ ứng dụng đặt khoá to bằng một giá trị chẳng hạn như /topics/yourTopic.
Nhà phát triển có thể chọn bất kỳ tên chủ đề nào khớp với biểu thức chính quy: "/topics/[a-zA-Z0-9-_.~%]+".
Để gửi đến các tổ hợp của nhiều chủ đề, máy chủ ứng dụng phải đặt khoá condition (thay vì khoá to) thành một điều kiện boolean chỉ định các chủ đề mục tiêu. Ví dụ: để gửi thông báo đến các thiết bị đã đăng ký TopicA và TopicB hoặc TopicC:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
Trước tiên, FCM sẽ đánh giá mọi điều kiện trong dấu ngoặc đơn, sau đó đánh giá biểu thức từ trái sang phải. Trong biểu thức trên, người dùng đã đăng ký theo dõi một chủ đề bất kỳ sẽ không nhận được thông báo. Tương tự như vậy, người dùng không đăng ký TopicsA sẽ không nhận được thông báo này. Những cách kết hợp này nhận được:
- Chủ đềA và Chủ đềB
- TopicsA và TopicsC
Bạn có thể đưa tối đa 5 chủ đề vào biểu thức có điều kiện và chúng tôi hỗ trợ dấu ngoặc đơn.
Các toán tử được hỗ trợ: &&, ||.
Yêu cầu POST qua HTTP theo chủ đề
Gửi đến một chủ đề duy nhất:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Gửi đến các thiết bị đã đăng ký theo dõi chủ đề "chó" hoặc "mèo":
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Phản hồi HTTP theo chủ đề
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Thông báo SAML chủ đề
Gửi đến một chủ đề duy nhất:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
Gửi đến các thiết bị đã đăng ký theo dõi chủ đề "chó" hoặc "mèo":
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
Phản hồi SAML chủ đề
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Có thể mất tới 30 giây để máy chủ FCM trả về phản hồi thành công hoặc không thành công cho các yêu cầu gửi chủ đề. Hãy nhớ đặt giá trị thời gian chờ của máy chủ ứng dụng trong yêu cầu cho phù hợp.
Gửi tin nhắn đến các nhóm thiết bị
Việc gửi thông báo tới một nhóm thiết bị bằng các API cũ không dùng nữa cũng rất giống với việc gửi thông báo tới một thiết bị riêng lẻ. Đặt tham số to thành khoá thông báo duy nhất cho nhóm thiết bị.
Các ví dụ trong phần này cho thấy cách gửi thông báo dữ liệu đến các nhóm thiết bị trong các giao thức HTTP và phiên bản giao thức RCS cũ.
Yêu cầu POST qua HTTP của nhóm thiết bị
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
"to": "aUniqueKey",
"data": {
"hello": "This is a Firebase Cloud Messaging Device Group Message!",
}
}
Phản hồi HTTP của nhóm thiết bị
Dưới đây là ví dụ về "thành công" – notification_key
có 2 mã thông báo đăng ký được liên kết và thông báo đã
được gửi thành công đến cả hai mã đó:
{
"success": 2,
"failure": 0
}
Dưới đây là ví dụ về "thành công một phần" – notification_key có 3 mã thông báo đăng ký được liên kết. Chỉ gửi thành công thông báo tới 1 trong số các mã thông báo
đăng ký. Thông báo phản hồi liệt kê các mã thông báo đăng ký (registration_ids) không nhận được thông báo:
{
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}
Khi không gửi được thông báo đến một hoặc nhiều mã thông báo đăng ký liên kết với notification_key, máy chủ ứng dụng sẽ thử lại bằng thời gian đợi giữa các lần thử lại.
Nếu máy chủ cố gắng gửi thông báo đến một nhóm thiết bị không có thành viên nào, thì phản hồi sẽ có dạng như sau (không có thành công và 0 lỗi):
{
"success": 0,
"failure": 0
}
Thông báo RCS của nhóm thiết bị
<message id="">
<gcm xmlns="google:mobile:data">
{
"to": "aUniqueKey",
"message_id": "m-1366082849205" ,
"data": {
"hello":"This is a Firebase Cloud Messaging Device Group Message!"
}
}
</gcm>
</message>
Phản hồi SAML cho nhóm thiết bị
Khi thông báo được gửi thành công đến một thiết bị bất kỳ trong nhóm, máy chủ kết nối AirPlay sẽ phản hồi bằng một ACK. Nếu tất cả tin nhắn gửi đến tất cả các thiết bị trong nhóm đều không thành công, thì máy chủ kết nối RCS sẽ phản hồi bằng thông báo NACK.
Dưới đây là ví dụ về "thành công" – notification_key
có 3 mã thông báo đăng ký liên kết và thông báo đã
được gửi thành công đến tất cả các mã đó:
{
"from": "aUniqueKey",
"message_type": "ack",
"success": 3,
"failure": 0,
"message_id": "m-1366082849205"
}
Dưới đây là ví dụ về "thành công một phần" – notification_key có 3 mã thông báo đăng ký được liên kết. Chỉ gửi thành công thông báo tới 1 trong số các mã thông báo
đăng ký. Thông báo phản hồi liệt kê các mã thông báo đăng ký không nhận được thông báo:
{
"from": "aUniqueKey",
"message_type": "ack",
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}
Khi máy chủ kết nối FCM không thể gửi đến tất cả các thiết bị trong nhóm. Máy chủ ứng dụng sẽ nhận được một phản hồi Nack.
Để biết danh sách đầy đủ các tuỳ chọn thông báo, hãy xem thông tin tham khảo của giao thức máy chủ kết nối mà bạn đã chọn, HTTP hoặc XMPP.
Phương thức gửi cũ của SDK dành cho quản trị viên Firebase
SDK Node.js của Quản trị viên Firebase hỗ trợ các phương thức gửi thông báo
(FCM) dựa trên
API máy chủ FCM cũ.
Các phương thức này chấp nhận các đối số khác so với phương thức send().
Bạn nên sử dụng phương thức send() bất cứ khi nào có thể và chỉ sử dụng các phương thức được mô tả trong trang này khi gửi thông báo đến các thiết bị hoặc nhóm thiết bị riêng lẻ.
Gửi đến từng thiết bị
Bạn có thể chuyển mã thông báo đăng ký đến phương thức sendToDevice() để gửi thông báo đến thiết bị đó:
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';
// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
data: {
score: '850',
time: '2:45'
}
};
// Send a message to the device corresponding to the provided
// registration token.
getMessaging().sendToDevice(registrationToken, payload)
.then((response) => {
// See the MessagingDevicesResponse reference documentation for
// the contents of response.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Phương thức sendToDevice() cũng có thể gửi một thông báo phát đa hướng (tức là một thông báo đến nhiều thiết bị) bằng cách truyền một mảng mã thông báo đăng ký thay vì chỉ truyền một mã thông báo đăng ký:
Node.js
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...',
// ...
'ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf...'
];
// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
data: {
score: '850',
time: '2:45'
}
};
// Send a message to the devices corresponding to the provided
// registration tokens.
getMessaging().sendToDevice(registrationTokens, payload)
.then((response) => {
// See the MessagingDevicesResponse reference documentation for
// the contents of response.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Phương thức sendToDevice() trả về một lời hứa đã được phân giải bằng đối tượng MessagingDevicesResponse chứa phản hồi từ FCM. Loại dữ liệu trả về có cùng định dạng khi truyền một mã thông báo đăng ký hoặc một mảng mã thông báo đăng ký.
Một số trường hợp, chẳng hạn như lỗi xác thực hoặc giới hạn tốc độ, khiến toàn bộ thông báo không xử lý được. Trong những trường hợp này, lời hứa được sendToDevice() trả về sẽ bị từ chối kèm theo lỗi. Để xem danh sách đầy đủ các mã lỗi, bao gồm nội dung mô tả và các bước khắc phục, hãy xem bài viết Các lỗi về API FCM dành cho quản trị viên.
Gửi đến một nhóm thiết bị
Phương thức sendToDeviceGroup() cho phép bạn gửi thông báo đến một nhóm thiết bị bằng cách chỉ định khoá thông báo cho nhóm thiết bị đó:
Node.js
// See the "Managing device groups" link above on how to generate a
// notification key.
const notificationKey = 'some-notification-key';
// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
data: {
score: '850',
time: '2:45'
}
};
// Send a message to the device group corresponding to the provided
// notification key.
getMessaging().sendToDeviceGroup(notificationKey, payload)
.then((response) => {
// See the MessagingDeviceGroupResponse reference documentation for
// the contents of response.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Phương thức sendToDeviceGroup() trả về một lời hứa đã được phân giải bằng đối tượng MessagingDevicesResponse chứa phản hồi từ FCM.
Một số trường hợp, chẳng hạn như lỗi xác thực hoặc giới hạn tốc độ, khiến toàn bộ thông báo không xử lý được. Trong những trường hợp này, lời hứa được sendToDeviceGroup() trả về sẽ bị từ chối kèm theo lỗi. Để xem danh sách đầy đủ các mã lỗi, bao gồm nội dung mô tả và các bước khắc phục, hãy xem bài viết Các lỗi về API FCM dành cho quản trị viên.
Xác định tải trọng thông báo
Các phương thức trên dựa trên giao thức cũ của FCM chấp nhận trọng tải tin nhắn làm đối số thứ hai và hỗ trợ cả thông báo và thông báo dữ liệu.
Bạn có thể chỉ định một hoặc cả hai loại thông báo bằng cách tạo một đối tượng bằng các khoá data và / hoặc notification. Ví dụ: dưới đây là cách xác định các loại tải trọng thông báo khác nhau:
Tin nhắn thông báo
const payload = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
}
};
Thông báo dữ liệu
const payload = {
data: {
score: '850',
time: '2:45'
}
};
Tin nhắn kết hợp
const payload = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
data: {
stock: 'GOOG',
open: '829.62',
close: '635.67'
}
};
Các gói dữ liệu thông báo thông báo có một tập con thuộc tính hợp lệ được xác định trước và sẽ khác một chút tuỳ thuộc vào hệ điều hành trên thiết bị di động mà bạn đang nhắm đến.
Hãy xem tài liệu tham khảo về NotificationMessagePayload để biết danh sách đầy đủ.
Các phần tải thông báo dữ liệu bao gồm các cặp khoá-giá trị tuỳ chỉnh với một số hạn chế, bao gồm cả việc tất cả giá trị đều phải là chuỗi. Hãy xem tài liệu tham khảo về DataMessagePayload để biết danh sách đầy đủ các quy định hạn chế.
Xác định các tuỳ chọn thông báo
Các phương thức nêu trên dựa trên giao thức cũ của FCM chấp nhận đối số thứ ba không bắt buộc chỉ định một số tuỳ chọn cho thông báo. Ví dụ: sau đây là ví dụ gửi một thông báo có mức độ ưu tiên cao đến một thiết bị sẽ hết hạn sau 24 giờ:
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';
// See the "Defining the message payload" section above for details
// on how to define a message payload.
const payload = {
notification: {
title: 'Urgent action needed!',
body: 'Urgent action is needed to prevent your account from being disabled!'
}
};
// Set the message as high priority and have it expire after 24 hours.
const options = {
priority: 'high',
timeToLive: 60 * 60 * 24
};
// Send a message to the device corresponding to the provided
// registration token with the provided options.
getMessaging().sendToDevice(registrationToken, payload, options)
.then((response) => {
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Hãy xem tài liệu tham khảo về MessagingOptions để biết danh sách đầy đủ các tuỳ chọn có sẵn.