Khi dùng SDK quản trị của Firebase hoặc giao thức máy chủ ứng dụng FCM, bạn có thể tạo yêu cầu tin nhắn 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 tin nhắn với tải trọng thông báo được tạo của 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 thông báo chứa cả hai loại tải trọng. Xem Loại thông báo để biết thêm thông tin.
Các ví dụ trong trang này trình bày cách gửi thông báo bằng SDK dành cho quản trị viên của Firebase (có hỗ trợ cho Nút, Java, Python, C#, và Bắt đầu) và Giao thức HTTP phiên bản 1. Ngoài ra, còn có hướng dẫn về việc gửi thông báo qua giao thức HTTP và XMPP cũ.
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 chuyển mã thông báo đăng ký của thiết bị đó dưới dạng hiển 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ý.
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"
}
}
}
Lệnh 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
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 phát đa hướng một thông báo vào danh sách mã thông báo đăng ký thiết bị. Bạn có thể chỉ định tối đa 500 thiết bị mã thông báo đăng ký cho mỗi lần 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à danh sách các mã thông báo tương ứng với thứ tự của đầ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 có 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 thư đến các chủ đề
Sau khi bạn tạo một chủ đề, bằng cách đăng ký các phiên bản ứng dụng khách để chủ đề ở phía máy khách hoặc thông qua server API, bạn có thể gửi thông báo đến chủ đề. Nếu đây là lần đầu tiên bạn tạo yêu cầu gửi cho FCM, xem hướng dẫn về môi trường máy chủ và FCM cho thông tin quan trọng về nền tảng và chế độ thiết lập.
Trong logic gửi trên phần phụ trợ, hãy chỉ định tên chủ đề mà bạn muốn như được hiển thị:
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"
}
}
}
Lệnh 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ư đến một tổ hợp chủ đề,
chỉ định điều kiện, là biểu thức boolean chỉ định
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 đá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ý
bất kỳ chủ đề nào đều không nhận được thông báo. Tương tự, một người dùng không
đăng ký TopicA không nhận được thông báo. Những cách kết hợp này
nhận email:
TopicAvàTopicBTopicAvàTopicC
Bạn có thể đưa 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",
}
}
}
Lệnh 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 phiên bản 1. Nếu bạn đang gửi đến các nhóm thiết bị bằng API gửi cũ không được dùng nữa cho HTTP hay XMPP hay 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 các giao thức cũ, chúng tôi đặc biệt khuyên bạn di chuyển sang API HTTP phiên bản 1 trong thời gian sớm nhất có thể. API gửi cũ sẽ bị vô hiệu hoá và bị xoá vào tháng 6 năm 2024.
Cách gửi tin nhắn đến một nhóm thiết bị rất giống với việc gửi
tin nhắn đến một thiết bị riêng lẻ, sử dụng cùng một phương pháp để
uỷ quyền gửi yêu cầu. Đặt token
vào 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ô duy nhất và gửi tất cả bằng một lệnh gọi API duy nhất, với hiệu suất tăng đáng kể so với việc gửi các yêu cầu HTTP riêng biệt cho từng thư.
Bạn có thể dùng tính năng này để tạo và gửi một nhóm tin nhắn tuỳ chỉnh đế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ể. Bạn có thể sử dụng tính năng này khi cần gửi đồng thời thông điệp đến các đối tượng khác nhau với các thành phần thông tin chi tiết trong nội dung thư.
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 hỗ trợ khởi động trực tiếp (chỉ Android)
Bạn có thể gửi tin nhắn đến các thiết bị ở chế độ khởi động trực tiếp bằng cách sử dụng HTTP phiên bản 1 hoặc API HTTP cũ. Trước khi gửi đến 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ị khách nhận tin nhắn FCM ở chế độ khởi động trực tiếp.
Gửi bằng API HTTP FCM v1
Lời mời nhắn tin phải bao gồm khoá "direct_boot_ok" : true trong
AndroidConfig tuỳ chọn trong 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ũ FCM
Lời mời nhắn tin phải bao gồm khoá "direct_boot_ok" : true ở trên cùng
cấp 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
}
Thư được gửi bằng khoá này trong nội dung yêu cầu có thể được 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ế độ đó).
Tuỳ chỉnh thông điệp 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 thông báo của bạn
yêu cầu đặt tất cả các trường có sẵn trong
message
. Điều này bao gồm:
- một tập hợp trường chung để tất cả phiên bản ứng dụng diễn giải nhận được tin nhắn.
- tập hợp các 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 phiên bản ứng dụng chạy trên nền tảng đã chỉ định.
Các quy tắc chặn theo nền tảng cụ thể giúp bạn linh hoạt tuỳ chỉnh thông báo cho nền tảng khác nhau để đảm bảo rằng chúng được xử lý chính xác khi nhận được. Chiến lược phát hành đĩa đơn Phần phụ trợ FCM sẽ xem xét tất cả các tham số được chỉ định và tuỳ chỉnh cho từng nền tảng.
Trường hợp sử dụng các trường phổ biến
Sử dụng các trường thông thường khi bạn:
- Nhắm đến các phiên bản ứng dụng trên tất cả nền tảng – Apple, Android và web
- Đang gửi tin nhắn đến các chủ đề
Tất cả phiên bản ứng dụng, bất kể nền tảng, đều có thể diễn giải các thuật ngữ phổ biến sau trường:
Trường hợp 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 chung
Bất cứ khi nào bạn chỉ muốn gửi giá trị đến các nền tảng cụ thể, đừng sử dụng các trường chung; sử dụng các trường dành riêng cho nền tảng. Ví dụ: để gửi thông báo chỉ dành cho các nền tảng và web của Apple nhưng không dành cho Android, bạn phải sử dụng hai nhóm một trường cho Apple và một trường cho web.
Khi bạn gửi thông báo bằng những các lựa chọn phân phối, sử dụng các trường dành riêng cho nền tảng để đặt chúng. Bạn có thể chỉ định các giá trị khác nhau cho mỗi nền tảng nếu bạn muốn. Tuy nhiên, ngay cả khi bạn muốn đặt cùng một giá trị trên nền tảng, bạn phải sử dụng các trường dành riêng cho nền tảng. Lý do là 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 là thời gian hết hạn được đặt trên Android tính bằng giây, còn trên Apple, thời gian hết hạn được đặt là date hết hạn.
Ví dụ: tin nhắn thông báo có các lựa chọn về màu sắc và biểu tượng
Trong ví dụ này, yêu cầu gửi sẽ gửi một nội dung và tiêu đề thông báo chung cho tất cả nền tảng, mà còn gửi một số ghi đè dành riêng cho nền tảng tới Android thiết bị.
Đối với Android, yêu cầu này sẽ thiết lập một biểu tượng và màu đặc biệt để hiển thị trên thiết bị Android. Như đã nêu trong tài liệu tham khảo cho AndroidNotification, màu được chỉ định theo định dạng #rrggbb và hình ảnh phải là đối tượng có thể vẽ cục bộ cho ứng dụng Android.
Dưới đây là hiệu ứng hình ảnh gần đúng 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"
}
}
}
}
Xem Tài liệu tham khảo về HTTP phiên bản 1 để biết đầy đủ thông tin chi tiết về các khoá có sẵn trong các khối dành riêng cho từng nền tảng trong nội dung thư.
Ví dụ: nội dung 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 cho tất cả nền tảng, nhưng cũng gửi một hình ảnh. Đây là số liệu ước tính 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"
}
}
}
}
Xem Tài liệu tham khảo về HTTP phiên bản 1 để biết đầy đủ thông tin chi tiết về các khoá có sẵn trong các khối dành riêng cho từng nền tảng trong nội dung thư.
Ví dụ: nội dung thông báo có hành động nhấp chuột được liên kết
Trong ví dụ sau đây, yêu cầu gửi sẽ gửi một tiêu đề thông báo chung cho tất cả nền tảng, mà còn gửi một hành động để ứng dụng thực hiện nhằm phản hồi người dùng tương tác với thông báo. Dưới đây là hiệu ứng hình ảnh gần đúng 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"
}
}
}
}
Xem Tài liệu tham khảo về HTTP phiên bản 1 để biết đầy đủ thông tin chi tiết về các khoá có sẵn trong các khối dành riêng cho từng nền tảng trong nội dung thư.
Ví dụ: nội dung thông báo có các lựa chọn bản địa hoá
Ví dụ sau đây về việc gửi yêu cầu sẽ gửi các lựa chọn bản địa hoá để ứng dụng hiển thị các thông báo đã bản địa hoá. Dưới đây là hiệu ứng hình ảnh gần đúng 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"],
},
},
},
},
},
}'
Xem Tài liệu tham khảo về HTTP phiên bản 1 để biết đầy đủ thông tin chi tiết về các khoá có sẵn trong các khối dành riêng cho từng nền tảng trong nội dung thư.
Mã lỗi REST cho API HTTP phiên bản 1
Các phản hồi lỗi HTTP cho API HTTP phiên bản 1 chứa mã lỗi, thông báo lỗi và trạng thái lỗi.
Các bảng này cũng có thể chứa một mảng details cung cấp thêm thông tin chi tiết 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ừ một yêu cầu API HTTP v1 có giá trị không hợp lệ trong 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ừ một yêu cầu API HTTP v1 với 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 cho biết có lỗi trong giá trị yêu cầu. Ví dụ thứ hai thuộc loại type.googleapis.com/google.firebase.fcm.v1.FcmError có một lỗi cụ thể trong 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 FCM v1 REST API và nội dung mô tả.
| Mã lỗi | Các bước mô tả và giải quyết vấn đề |
|---|---|
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ệ. Một 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ể bao gồm thông tin đă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ệ: 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ự khác. Tên gói không hợp lệ: Đảm bảo thông báo được gửi đến mã thông báo đăng ký có tên gói khớp với giá trị đã chuyển trong yêu cầu. Tin nhắn 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 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 thư hoặc 2048 byte đối với chủ đề. Dữ liệ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 dữ liệu tải trọng không chứa khoá (chẳng hạn như từ, gcm hoặc bất kỳ giá trị nào có tiền tố là google) mà FCM sử dụng nội bộ. Lưu ý rằng FCM cũng sử dụng một số từ (chẳng hạn như thu gọn_key) 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 đè. TTL không hợp lệ: Kiểm tra để đảm bảo giá trị dùng trong ttl là một số nguyên biểu thị khoảng thời gian tính bằng giây trong khoảng từ 0 đến 2.419.200 (4 tuần). Tham số không hợp lệ: Kiểm tra để đảm bảo các tham số đã cung cấp có tên và loại phù hợp. |
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ể là 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 rằng 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ể hết hiệu lực trong một số trường hợp, bao gồm: – Nếu ứng dụng khách huỷ đăng ký bằng FCM. – Nếu ứng dụng khách tự động bị huỷ đăng ký, thì điều này có thể xảy ra khi 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 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 chưa được định cấu hình để nhận thông báo. Đối với tất cả các trường hợp như vậy, hãy xoá mã thông báo đăng ký này khỏi máy chủ ứng dụng rồi ngừng sử dụng mã để gửi thông báo. |
SENDER_ID_MISMATCH (Mã lỗi HTTP = 403) Mã nhận dạng người gửi đã xác thực khác với mã nhận dạng 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 một ứng dụng khách đăng ký FCM, ứng dụng này phải chỉ định những người gửi đượ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 thư đến ứng dụng. Nếu bạn chuyển sang một 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. Hàm mở rộng thuộc loại google.rpc.QuotaFailure được trả về để chỉ định hạn mức đã vượt quá. |
Lỗi này có thể do vượt quá hạn mức tốc độ tin nhắn trên thiết bị, 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 của tin nhắn quá cao. Bạn phải giảm tổng tốc độ 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ốc độ tin nhắn trên thiết bị: Tốc độ tin nhắn gửi đến một thiết bị cụ thể quá cao. Xem giới hạn tốc độ nhắn tin cho một thiết bị. Hãy giảm số lượng tin nhắn được gửi đến thiết bị này và sử 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ý về một chủ đề cụ thể quá cao. Hãy giảm số lượng thư được gửi cho chủ đề này và 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ử 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. Hãy thử yêu cầu lại, nhưng bạn phải: – Thực hiện tiêu đề Retry-After nếu tiêu đề này có trong phản hồi từ Máy chủ kết nối FCM. - Triển khai thuật toán thời gian đợi luỹ thừa trong cơ chế thử lại của bạn. (ví dụ: nếu bạn đã đợi một giây trước khi thử lại lần đầu tiên, hãy đợi ít nhất hai giây trước lần thử tiếp theo, sau đó đợi 4 giây và tiếp tục như vậy). Nếu bạn đang gửi nhiều thư, hãy cân nhắc áp dụng hiệu ứng dao động. Để biết thêm thông tin, hãy xem phần Xử lý các lần thử lại. Những người gửi gây ra vấn đề có nguy cơ bị 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ử yêu cầu lại theo các đề xuất sau trong phần Xử lý các lần thử lại. Nếu lỗi vẫn tiếp diễn, vui lòng liên hệ với nhóm hỗ trợ Firebase. |
Thiếu hoặc thiếu chứng chỉ APN THIRD_PARTY_AUTH_ERROR (mã lỗi HTTP = 401) hoặc khoá xác thực thông báo đẩy trên web. |
Không thể gửi thông báo nhắm đến thiết bị iOS hoặc đăng ký thông báo đẩy trên web. Kiểm tra tính hợp lệ của thông tin xác thực phát triển và phát hành chính thức. |
Mã lỗi của quản trị viên
Bảng sau đây liệt kê các mã lỗi FCM API Quản trị Firebase và nội dung mô tả, bao gồm cả những bước giải quyết được đề xuất.
| Mã lỗi | Các bước mô tả và giải quyết vấn đề |
|---|---|
messaging/invalid-argument |
Đã cung cấp đối số không hợp lệ cho phương thức FCM. Lỗi tin nhắn sẽ 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 sẽ chứa thông tin bổ sung. |
messaging/invalid-payload |
Bạn đã cung cấp một đối tượng tải trọng tin nhắn không hợp lệ. Thông báo lỗi sẽ 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
tài liệu cho
DataMessagePayload đối với 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. Chiến lược phát hành đĩa đơn giới hạn là 4096 byte cho hầu hết thư. Đối với các thư gửi đến chủ đề, giới hạn là 2048 byte. Chiến lược phát hành đĩa đơn 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 tùy chọn thông báo không hợp lệ. Thông báo lỗi sẽ 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ệ. Hãy đảm bảo thông tin này khớp với thông tin đăng ký mã thông báo 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 bổ sung thêm ký tự vào ký tự. |
messaging/registration-token-not-registered |
Mã thông báo đăng ký đã cung cấp chưa được đăng ký. Hợp lệ trước đây
mã thông báo đăng ký có thể bị huỷ đăng ký vì nhiều lý do,
bao gồm:
|
messaging/invalid-package-name |
Thư được gửi tới mã thông báo đăng ký có tên gói có
không khớp với giá trị được cung cấp
restrictedPackageName.
|
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 đã gửi đến thiết bị hoặc chủ đề này và không thử lại ngay đang gửi đến mục tiêu này. |
messaging/device-message-rate-exceeded |
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. |
messaging/topics-message-rate-exceeded |
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ư được gửi về chủ đề này và không gửi ngay thử gửi lại đến chủ đề này. |
messaging/too-many-topics |
Mã thông báo đăng ký đã được đăng ký với số lượng chủ đề tối đa và không thể đăng ký kênh nào nữa. |
messaging/invalid-apns-credentials |
Không thể gửi thư nhắm mục tiêu đến thiết bị Apple vì chứng chỉ SSL APN bắt buộc chưa được tải lên hoặc đã hết hạn. Xem hiệu lực của chứng chỉ phát triển và chứng chỉ sản xuất. |
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 đến thiết bị tương ứng với đăng ký đã cung cấp mã thông báo. Đả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 Thêm Firebase vào ứng dụng của bạn để biết tài liệu về cách xác thực SDK quản trị Firebase. |
messaging/authentication-error |
SDK không thể xác thực với máy chủ FCM. Đảm bảo bạn xác thực SDK quản trị Firebase bằng thông tin đăng nhập có để gửi thông báo FCM. Xem Thêm Firebase vào ứng dụng của bạn để biết tài liệu về cách xác thực SDK quản trị 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 bạn phải:
|
messaging/internal-error |
Máy chủ FCM đã gặp lỗi trong khi cố gắng xử lý
của bạn. 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àng messaging/server-unavailable ở trên. Nếu
vẫn xảy ra lỗi, vui lòng báo cáo sự cố cho
Kênh hỗ trợ Báo cáo lỗi.
|
messaging/unknown-error |
Đã trả về lỗi máy chủ không xác định. Xem phản hồi thô của máy chủ trong để biết thêm chi tiết. Nếu bạn gặp lỗi này, hãy báo cáo thông báo lỗi đầy đủ đến Kênh hỗ trợ Báo cáo lỗi. |
Gửi thông báo bằng giao thức máy chủ ứng dụng cũ
Nếu bạn hiện đang sử dụng các giao thức cũ, hãy tạo yêu cầu thông báo như minh hoạ trong phần này. Xin lưu ý rằng nếu bạn gửi đến nhiều nền tảng qua HTTP thì giao thức v1 có thể đơn giản hoá đáng kể yêu cầu tin nhắn của bạn.
Gửi tin nhắn đến các thiết bị cụ thể
Để gửi thông báo tới các thiết bị cụ thể, hãy đặt khoá to thành gói đăng ký
mã thông báo cho phiên bản ứng dụng cụ thể. Xem thông tin thiết lập ứng dụng cho
để 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 XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
Phản hồi XMPP
<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 XMPP cung cấp một số tuỳ chọn khác cho phản hồi. Xem Định dạng phản hồi của máy chủ.
Để xem danh sách đầy đủ các tuỳ chọn thông báo có sẵn khi gửi xuống dưới thông báo cho ứ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 HTTP hoặc XMPP.
Gửi thư đến các chủ đề
Việc gửi tin nhắn đến chủ đề Giải pháp gửi thông báo qua đám mây của Firebase rất giống với
gửi tin nhắn đến một thiết bị cá nhân hoặc một nhóm người dùng. Ứng dụng
máy chủ sẽ đặt khoá to có giá trị 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) cho 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ý
đến TopicA và TopicB hoặc
TopicC:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
Trước tiên, FCM đá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, một người dùng đã đăng ký bất kỳ một chủ đề nào không nhận được tin nhắn. Tương tự như vậy, một người dùng không đăng ký TopicA không nhận được tin nhắn. Những tổ hợp này nhận được mã:
- Chủ đề A và Chủ đề B
- Chủ đề A và Chủ đề C
Bạn có thể đưa tối đa 5 chủ đề vào biểu thức có điều kiện và có 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ủ đề:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
Gửi tới các thiết bị đã đăng ký 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"
}
Tin nhắn XMPP theo chủ đề
Gửi đến một chủ đề:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
Gửi tới các thiết bị đã đăng ký chủ đề "chó" hoặc "mèo":
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
Phản hồi XMPP chủ đề
// Success example:
{
"message_id": "1023456"
}
// failure example:
{
"error": "TopicsMessageRateExceeded"
}
Có thể mất tối đa 30 giây trước khi Máy chủ FCM trả về phản hồi thành công hay không thành công cho các yêu cầu gửi chủ đề. Đảm bảo để đặ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ị
Gửi thông báo đến một nhóm thiết bị bằng API cũ không dùng nữa
rất giống với việc gửi
tin nhắn đến một thiết bị riêng lẻ. Đặt tham số to
vào 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 dữ liệu
gửi thông báo đến các nhóm thiết bị trong giao thức HTTP và XMPP cũ.
Yêu cầu POST qua HTTP cho 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ị
Sau đây là một ví dụ về từ "thành công" – notification_key
có liên kết với 2 mã thông báo đăng ký và tin nhắn là
đã gửi thành công đến cả hai email:
{
"success": 2,
"failure": 0
}
Sau đây là ví dụ về "thành công một phần" –
notification_key đã liên kết với 3 mã thông báo đăng ký
với nó. Thư đã được gửi thành công đến 1 trong số các đăng ký
mã thông báo. Tin nhắn phản hồi liệt kê các mã thông báo đăng ký
(registration_ids) không nhận được thư:
{
"success":1,
"failure":2,
"failed_registration_ids":[
"regId1",
"regId2"
]
}
Khi tin nhắn không được gửi tới một hoặc nhiều
mã thông báo đăng ký được liên kết với notification_key,
máy chủ ứng dụng nên 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 tin nhắn đến một nhóm thiết bị không có thành viên, phản hồi sẽ có dạng như sau, với 0 thành công và 0 không thành công:
{
"success": 0,
"failure": 0
}
Thông báo XMPP 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 XMPP của nhóm thiết bị
Khi tin nhắn được gửi đến một thiết bị bất kỳ trong nhóm thành công thì máy chủ kết nối XMPP sẽ phản hồi bằng một ACK. Nếu không gửi được tất cả tin nhắn đến tất cả thiết bị trong nhóm, kết nối XMPP máy chủ phản hồi bằng một NACK.
Sau đây là ví dụ về "thành công" – notification_key
có 3 mã thông báo đăng ký được liên kết với thông báo và thông báo này là
đã gửi thành công đến tất cả email:
{
"from": "aUniqueKey",
"message_type": "ack",
"success": 3,
"failure": 0,
"message_id": "m-1366082849205"
}
Sau đây là ví dụ về "thành công một phần" –
notification_key đã liên kết với 3 mã thông báo đăng ký
với nó. Thư đã được gửi thành công đến 1 trong số các đăng ký
mã thông báo. Tin nhắn phản hồi liệt kê các mã thông báo đăng ký
không nhận được thư:
{
"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 tới tất cả thiết bị trong nhóm. Máy chủ ứng dụng sẽ nhận được phản hồi nack.
Để biết danh sách đầy đủ các lựa chọn về thông báo, hãy xem thông tin tham khảo cho 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ũ SDK quản trị của Firebase
SDK Node.js dành cho quản trị viên của Firebase có hỗ trợ các phương thức để gửi
(FCM) dựa trên
API máy chủ FCM cũ.
Các phương thức này chấp nhận nhiều đối số 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ỉ dùng phương thức
các phương thức được mô tả trên trang này khi gửi thông báo đến từng thiết bị hoặc
nhóm thiết bị.
Gửi đến các thiết bị cá nhân
Bạn có thể chuyển mã thông báo đăng ký đến
sendToDevice()
để gửi tin nhắn đế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 multicast (truyền
thông báo đến nhiều thiết bị) bằng cách chuyển một mảng mã thông báo đăng ký
của 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 giải quyết bằng một
MessagingDevicesResponse
đối tượng chứa phản hồi từ FCM. Loại dữ liệu trả về có cùng
khi truyền một mã thông báo đăng ký hoặc một mảng đăng ký
mã thông báo.
Một số trường hợp như lỗi xác thực hoặc giới hạn số lượng yêu cầu là nguyên nhân
không thể xử lý thông báo. Trong những trường hợp này, lời hứa được trả về bởi
sendToDevice() bị từ chối do có lỗi. Để xem danh sách đầy đủ các mã lỗi,
bao gồm cả nội dung mô tả và các bước giải quyết, hãy xem
Lỗi API FCM dành cho quản trị viên.
Gửi đến một nhóm thiết bị
Chiến lược phát hành đĩa đơn
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
phím 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 giải quyết bằng một
MessagingDevicesResponse
đối tượng chứa phản hồi từ FCM.
Một số trường hợp như lỗi xác thực hoặc giới hạn số lượng yêu cầu là nguyên nhân
không thể xử lý thông báo. Trong những trường hợp này, lời hứa được trả về bởi
sendToDeviceGroup() bị từ chối do có lỗi. Để xem danh sách đầy đủ các mã lỗi,
bao gồm cả nội dung mô tả và các bước giải quyết, hãy xem
Lỗi 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 pháp trên dựa trên giao thức cũ FCM
chấp nhận tải trọng tin nhắn làm đối số và hỗ trợ thứ hai
cả hai
thông báo và tin nhắn 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 data
và / hoặc notification. Ví dụ: sau đây là cách xác định các loại
tải trọng tin nhắn:
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'
}
};
Thông báo 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 tải trọng tin nhắn thông báo có một tập hợp con được xác định trước gồm các thuộc tính hợp lệ và
hơi khác nhau tuỳ thuộc vào hệ điều hành trên thiết bị di động mà bạn đang nhắm mục tiêu.
Hãy xem tài liệu tham khảo cho
NotificationMessagePayload
để xem danh sách đầy đủ.
Tải trọng thông báo dữ liệu bao gồm các cặp khoá-giá trị tuỳ chỉnh cùng với một vài
các hạn chế, bao gồm cả việc tất cả các giá trị đều phải là chuỗi. Xem
tài liệu tham khảo cho
DataMessagePayload
để xem 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 pháp trên dựa trên giao thức cũ FCM chấp nhận đối số thứ ba (không bắt buộc) chỉ định một số tuỳ chọn cho nội dung. Ví dụ: ví dụ sau đây gửi thông báo có mức độ ưu tiên cao đối với 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 cho
MessagingOptions
để xem danh sách đầy đủ các lựa chọn hiện có.