با استفاده از Firebase Admin SDK یا پروتکلهای سرور برنامه FCM ، میتوانید درخواستهای پیام بسازید و آنها را به این نوع اهداف ارسال کنید:
- نام موضوع
- وضعیت
- رمز ثبت دستگاه
- نام گروه دستگاه (فقط پروتکل)
میتوانید پیامهایی را با یک محموله اعلان متشکل از فیلدهای از پیش تعریفشده، یک محموله داده از فیلدهای تعریفشده توسط کاربر یا پیامی حاوی هر دو نوع بار ارسال کنید. برای اطلاعات بیشتر به انواع پیام مراجعه کنید.
مثالهای موجود در این صفحه نحوه ارسال پیامهای اعلان را با استفاده از Firebase Admin SDK (که از Node ، Java ، Python ، C# و Go پشتیبانی میکند) و پروتکل HTTP v1 نشان میدهد. همچنین راهنمایی برای ارسال پیام از طریق پروتکلهای قدیمی HTTP و XMPP وجود دارد.
ارسال پیام به دستگاه های خاص
برای ارسال به یک دستگاه خاص، رمز ثبت نام دستگاه را مطابق شکل ارسال کنید. برای کسب اطلاعات بیشتر در مورد نشانه های ثبت نام، اطلاعات راه اندازی مشتری برای پلتفرم خود را ببینید.
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);
});
جاوا
// 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);
پایتون
# 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)
برو
// 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)
سی شارپ
// 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);
استراحت
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
در صورت موفقیت، هر روش ارسال یک شناسه پیام را برمی گرداند. Firebase Admin SDK رشته ID را در قالب projects/{project_id}/messages/{message_id}
برمیگرداند. پاسخ پروتکل HTTP یک کلید JSON است:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
ارسال پیام به چندین دستگاه
Admin FCM APIs به شما امکان می دهد پیام را به لیستی از نشانه های ثبت دستگاه چندپخش کنید. شما می توانید تا 500 توکن ثبت دستگاه را در هر فراخوانی مشخص کنید.
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');
});
جاوا
// 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");
پایتون
# 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))
برو
// 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)
سی شارپ
// 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");
مقدار بازگشتی لیستی از نشانه ها است که با ترتیب توکن های ورودی مطابقت دارد. این زمانی مفید است که میخواهید بررسی کنید کدام نشانهها منجر به خطا شدهاند.
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);
}
});
جاوا
// 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);
}
پایتون
# 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))
برو
// 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)
}
سی شارپ
// 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}");
}
ارسال پیام به موضوعات
پس از ایجاد یک موضوع، یا با اشتراک نمونههای برنامه مشتری در موضوع سمت سرویس گیرنده یا از طریق API سرور ، میتوانید پیامهایی را به موضوع ارسال کنید. اگر این اولین باری است که درخواست ارسال درخواست برای FCM را ایجاد میکنید، راهنمای محیط سرور و FCM برای اطلاعات مهم پسزمینه و راهاندازی ببینید.
در منطق ارسال خود در باطن، نام موضوع مورد نظر را مطابق شکل مشخص کنید:
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);
});
جاوا
// 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);
پایتون
# 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)
برو
// 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)
سی شارپ
// 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);
استراحت
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
برای ارسال پیام به ترکیبی از موضوعات، یک شرط را مشخص کنید، که یک عبارت بولی است که موضوعات مورد نظر را مشخص می کند. برای مثال، شرایط زیر پیامهایی را به دستگاههایی ارسال میکند که مشترک TopicA
و TopicB
یا TopicC
هستند:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
FCM ابتدا هر شرایط داخل پرانتز را ارزیابی می کند و سپس عبارت را از چپ به راست ارزیابی می کند. در عبارت بالا، کاربری که در یک موضوع مشترک است، پیامی را دریافت نمی کند. به همین ترتیب، کاربری که در TopicA
مشترک نمی شود، پیام را دریافت نمی کند. این ترکیب ها آن را دریافت می کنند:
-
TopicA
وTopicB
-
TopicA
وTopicC
می توانید حداکثر پنج موضوع را در عبارت شرطی خود بگنجانید.
برای ارسال به یک شرط:
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);
});
جاوا
// 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);
پایتون
# 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)
برو
// 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)
سی شارپ
// 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);
استراحت
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
ارسال پیام به گروه های دستگاه
برای ارسال پیام به گروه های دستگاه، از HTTP v1 API استفاده کنید. اگر در حال حاضر با استفاده از APIهای ارسال قدیمی قدیمی برای HTTP یا XMPP یا هر یک از نسخههای قدیمیتر Firebase Admin SDK برای Node.js بر اساس پروتکلهای قدیمی، به گروههای دستگاه ارسال میکنید، اکیداً توصیه میکنیم که به HTTP v1 مهاجرت کنید. API در اولین فرصت APIهای ارسال قدیمی در ژوئن 2024 غیرفعال و حذف خواهند شد.
ارسال پیام به یک گروه دستگاه بسیار شبیه به ارسال پیام به یک دستگاه جداگانه است، با استفاده از همان روش برای تأیید درخواستهای ارسال . فیلد token
را روی کلید اعلان گروه تنظیم کنید:
استراحت
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!"
}
}
}
دستور 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
یک دسته پیام بفرستید
Admin SDK از ارسال پیامها به صورت دستهای پشتیبانی میکند. شما می توانید حداکثر 500 پیام را در یک دسته گروه بندی کنید و همه آنها را در یک تماس API ارسال کنید، با بهبود عملکرد قابل توجهی نسبت به ارسال درخواست های HTTP جداگانه برای هر پیام.
از این ویژگی می توان برای ایجاد مجموعه ای سفارشی از پیام ها و ارسال آنها به گیرندگان مختلف، از جمله موضوعات یا نشانه های ثبت دستگاه خاص استفاده کرد. از این ویژگی زمانی استفاده کنید که، برای مثال، نیاز دارید به طور همزمان پیام هایی را با جزئیات کمی متفاوت در متن پیام به مخاطبان مختلف ارسال کنید.
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');
});
جاوا
// 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");
پایتون
# 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))
برو
// 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)
سی شارپ
// 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");
ارسال پیامهای مستقیم با قابلیت بوت (فقط اندروید)
میتوانید با استفاده از HTTP v1 یا APIهای قدیمی HTTP، پیامها را در حالت بوت مستقیم به دستگاهها ارسال کنید. قبل از ارسال به دستگاهها در حالت بوت مستقیم، مطمئن شوید که مراحل فعال کردن دستگاههای سرویس گیرنده را برای دریافت پیامهای FCM در حالت راهاندازی مستقیم انجام دادهاید.
با استفاده از FCM v1 HTTP API ارسال کنید
درخواست پیام باید شامل کلید "direct_boot_ok" : true
در گزینه های AndroidConfig
بدنه درخواست باشد. به عنوان مثال:
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,
},
}
با استفاده از API HTTP قدیمی FCM ارسال کنید
درخواست پیام باید شامل کلید "direct_boot_ok" : true
در سطح بالای بدنه درخواست باشد. به عنوان مثال:
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
}
پیامهایی که با این کلید در بدنه درخواست ارسال میشوند میتوانند توسط برنامههای دستگاههایی که در حال حاضر در حالت بوت مستقیم هستند (و همچنین زمانی که در آن حالت نیستند) مدیریت کنند.
سفارشی کردن پیام ها در پلتفرم ها
Firebase Admin SDK و پروتکل FCM v1 HTTP هر دو به درخواست های پیام شما اجازه می دهند تمام فیلدهای موجود در شی message
را تنظیم کنند. این شامل:
- مجموعه ای مشترک از فیلدها که باید توسط همه نمونه های برنامه ای که پیام را دریافت می کنند تفسیر شوند.
- مجموعههایی از فیلدهای مخصوص پلتفرم، مانند
AndroidConfig
وWebpushConfig
، که فقط توسط نمونههای برنامهای که در پلتفرم مشخصشده اجرا میشوند تفسیر میشوند.
بلوکهای مخصوص پلتفرم به شما انعطافپذیری میدهند تا پیامها را برای پلتفرمهای مختلف سفارشی کنید تا اطمینان حاصل کنید که هنگام دریافت بهدرستی با آنها برخورد میشود. پشتیبان FCM تمام پارامترهای مشخص شده را در نظر می گیرد و پیام را برای هر پلتفرم سفارشی می کند.
زمان استفاده از فیلدهای مشترک
وقتی هستید از فیلدهای مشترک استفاده کنید:
- هدف قرار دادن نمونه های برنامه در همه پلتفرم ها - اپل، اندروید و وب
- ارسال پیام به موضوعات
همه نمونه های برنامه، صرف نظر از پلتفرم، می توانند فیلدهای مشترک زیر را تفسیر کنند:
چه زمانی از فیلدهای مخصوص پلتفرم استفاده کنیم
زمانی که می خواهید از فیلدهای مخصوص پلتفرم استفاده کنید:
- فیلدها را فقط به پلتفرم های خاص ارسال کنید
- علاوه بر فیلدهای مشترک، فیلدهای مخصوص پلتفرم را ارسال کنید
هر زمان که میخواهید مقادیر را فقط به پلتفرمهای خاصی ارسال کنید، از فیلدهای مشترک استفاده نکنید . از فیلدهای مخصوص پلتفرم استفاده کنید. به عنوان مثال، برای ارسال نوتیفیکیشن فقط به پلتفرمهای اپل و وب اما نه برای اندروید، باید از دو مجموعه فیلد جداگانه، یکی برای اپل و دیگری برای وب استفاده کنید.
هنگامی که پیام هایی با گزینه های تحویل خاص ارسال می کنید، از فیلدهای مخصوص پلتفرم برای تنظیم آنها استفاده کنید. در صورت تمایل می توانید مقادیر مختلفی را برای هر پلتفرم مشخص کنید. با این حال، حتی زمانی که میخواهید اساساً مقدار یکسانی را در بین پلتفرمها تنظیم کنید، باید از فیلدهای مخصوص پلتفرم استفاده کنید. این به این دلیل است که هر پلتفرم ممکن است مقدار را کمی متفاوت تفسیر کند - برای مثال، زمان برای زندگی در Android به عنوان زمان انقضا بر حسب ثانیه تنظیم می شود، در حالی که در اپل به عنوان تاریخ انقضا تنظیم می شود.
مثال: پیام اعلان با گزینه های رنگ و نماد
این درخواست ارسال مثال، عنوان و محتوای اعلان مشترک را به همه پلتفرمها ارسال میکند، اما برخی موارد لغو خاص پلتفرم را نیز به دستگاههای Android ارسال میکند.
برای اندروید، درخواست یک نماد و رنگ خاص را برای نمایش در دستگاه های اندرویدی تنظیم می کند. همانطور که در مرجع AndroidNotification ذکر شد، رنگ در قالب #rrggbb مشخص شده است، و تصویر باید یک منبع نماد قابل ترسیم محلی برای برنامه Android باشد.
در اینجا تقریبی از جلوه بصری روی دستگاه کاربر آورده شده است:
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);
});
جاوا
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();
پایتون
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',
)
برو
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",
}
سی شارپ
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",
};
استراحت
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"
}
}
}
}
برای جزئیات کامل کلیدهای موجود در بلوکهای مخصوص پلتفرم در متن پیام، به مستندات مرجع HTTP v1 مراجعه کنید.
مثال: پیام اعلان با یک تصویر سفارشی
مثال زیر درخواست ارسال یک عنوان اعلان مشترک را به همه پلتفرم ها ارسال می کند، اما یک تصویر نیز ارسال می کند. در اینجا تقریبی از جلوه بصری روی دستگاه کاربر آورده شده است:
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);
});
استراحت
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"
}
}
}
}
برای جزئیات کامل کلیدهای موجود در بلوکهای مخصوص پلتفرم در متن پیام، به مستندات مرجع HTTP v1 مراجعه کنید.
مثال: پیام اعلان با یک اقدام کلیک مرتبط
مثال زیر درخواست ارسال یک عنوان اعلان مشترک را به همه پلتفرمها ارسال میکند، اما همچنین اقدامی را برای برنامه ارسال میکند تا در پاسخ به تعامل کاربر با اعلان انجام دهد. در اینجا تقریبی از جلوه بصری روی دستگاه کاربر آورده شده است:
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);
});
استراحت
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"
}
}
}
}
برای جزئیات کامل کلیدهای موجود در بلوکهای مخصوص پلتفرم در متن پیام، به مستندات مرجع HTTP v1 مراجعه کنید.
مثال: پیام اعلان با گزینه های محلی سازی
مثال زیر درخواست ارسال گزینههای محلیسازی را برای مشتری ارسال میکند تا پیامهای محلی را نمایش دهد. در اینجا تقریبی از جلوه بصری روی دستگاه کاربر آورده شده است:
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);
});
استراحت
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"],
},
},
},
},
},
}'
برای جزئیات کامل کلیدهای موجود در بلوکهای مخصوص پلتفرم در متن پیام، به مستندات مرجع HTTP v1 مراجعه کنید.
کدهای خطا REST برای HTTP v1 API
پاسخ های خطای HTTP برای HTTP v1 API حاوی کد خطا، پیام خطا و وضعیت خطا است. آنها همچنین ممکن است حاوی یک آرایه details
با جزئیات بیشتر در مورد خطا باشند.
در اینجا دو نمونه پاسخ خطا آورده شده است:
مثال 1: پاسخ خطا از درخواست HTTP v1 API با مقدار نامعتبر در پیام داده
{
"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"
}
]
}
]
}
}
مثال 2: پاسخ خطا از یک درخواست API HTTP v1 با یک نشانه ثبت نام معتبر
{
"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"
}
]
}
}
توجه داشته باشید که هر دو پیام کد و وضعیت یکسانی دارند، اما آرایه جزئیات حاوی مقادیر در انواع مختلف است. نمونه اول دارای نوع type.googleapis.com/google.rpc.BadRequest
است که نشان دهنده خطا در مقادیر درخواست است. مثال دوم با نوع type.googleapis.com/google.firebase.fcm.v1.FcmError
دارای یک خطای خاص FCM است. برای بسیاری از خطاها، آرایه جزئیات حاوی اطلاعاتی است که برای اشکال زدایی و یافتن وضوح نیاز دارید.
جدول زیر کدهای خطای FCM v1 REST API و توضیحات آنها را فهرست می کند.
کد خطا | مراحل شرح و تفکیک |
---|---|
UNSPECIFIED_ERROR اطلاعات بیشتری در مورد این خطا در دسترس نیست. | هیچ کدام. |
INVALID_ARGUMENT (کد خطای HTTP = 400) پارامترهای درخواست نامعتبر بودند. پسوندی از نوع google.rpc.BadRequest برگردانده می شود تا مشخص شود کدام فیلد نامعتبر است. | دلایل بالقوه شامل ثبت نامعتبر، نام بسته نامعتبر، پیام خیلی بزرگ، کلید داده نامعتبر، TTL نامعتبر، یا سایر پارامترهای نامعتبر است. ثبت نام نامعتبر : فرمت رمز ثبت نامی که به سرور ارسال می کنید را بررسی کنید. مطمئن شوید که با نشانه ثبتی که برنامه مشتری از ثبت نام در FCM دریافت می کند مطابقت دارد. نشانه را کوتاه نکنید یا کاراکترهای اضافی اضافه نکنید. نام بسته نامعتبر : مطمئن شوید که پیام به نشانه ثبتی که نام بسته آن با مقدار ارسال شده در درخواست مطابقت دارد، خطاب شده است. پیام خیلی بزرگ : بررسی کنید که حجم کل دادههای محموله موجود در یک پیام از محدودیتهای FCM تجاوز نکند: 4096 بایت برای بیشتر پیامها، یا 2048 بایت در مورد پیامها به موضوعات. این شامل کلیدها و مقادیر می شود. کلید داده نامعتبر : بررسی کنید که دادههای محموله حاوی کلید (مانند از، یا gcm، یا هر مقداری که پیشوند Google است) نباشد که به صورت داخلی توسط FCM استفاده میشود. توجه داشته باشید که برخی از کلمات (مانند collapse_key) توسط FCM نیز استفاده می شوند اما در payload مجاز هستند، در این صورت مقدار payload با مقدار FCM لغو می شود. TTL نامعتبر : بررسی کنید که مقدار استفاده شده در ttl یک عدد صحیح باشد که مدت زمان بر حسب ثانیه را بین 0 تا 2,419,200 (4 هفته) نشان می دهد. پارامترهای نامعتبر : بررسی کنید که پارامترهای ارائه شده نام و نوع مناسبی داشته باشند. |
UNREGISTERED (کد خطای HTTP = 404) نمونه برنامه از FCM ثبت نشده است. این معمولاً به این معنی است که توکن مورد استفاده دیگر معتبر نیست و باید از یک توکن جدید استفاده شود. | این خطا می تواند ناشی از گم شدن توکن های ثبت نام یا توکن های ثبت نشده باشد. عدم ثبت : اگر هدف پیام یک مقدار token است، بررسی کنید که درخواست حاوی نشانه ثبت باشد.ثبت نشده : یک نشانه ثبت نام موجود ممکن است در تعدادی از سناریوها از بین برود، از جمله: - اگر برنامه مشتری با FCM لغو ثبت کند. - اگر برنامه مشتری به طور خودکار ثبت نشده باشد، در صورتی که کاربر برنامه را حذف نصب کند، ممکن است اتفاق بیفتد. به عنوان مثال، در iOS، اگر سرویس بازخورد APNs توکن APN را نامعتبر گزارش کند. - اگر رمز ثبت نام منقضی شود (برای مثال، ممکن است Google تصمیم بگیرد که نشانه های ثبت نام را به روز کند، یا نشانه APNs برای دستگاه های iOS منقضی شده است). - اگر برنامه سرویس گیرنده به روز شده است اما نسخه جدید برای دریافت پیام پیکربندی نشده است. برای همه این موارد، این رمز ثبت نام را از سرور برنامه حذف کنید و استفاده از آن برای ارسال پیام را متوقف کنید. |
SENDER_ID_MISMATCH (کد خطای HTTP = 403) شناسه فرستنده احراز هویت شده با شناسه فرستنده رمز ثبت نام متفاوت است. | یک نشانه ثبت نام به گروه خاصی از فرستندگان گره خورده است. هنگامی که یک برنامه مشتری برای FCM ثبت نام می کند، باید مشخص کند که کدام فرستنده مجاز به ارسال پیام است. هنگام ارسال پیام به برنامه مشتری باید از یکی از آن شناسه های فرستنده استفاده کنید. اگر به فرستنده دیگری بروید، نشانههای ثبتنام موجود کار نمیکنند. |
QUOTA_EXCEEDED (کد خطای HTTP = 429) از محدودیت ارسال برای هدف پیام فراتر رفت. پسوندی از نوع google.rpc.QuotaFailure برگردانده می شود تا مشخص شود از کدام سهمیه فراتر رفته است. | این خطا می تواند ناشی از فراتر از سهمیه نرخ پیام، فراتر از سهمیه نرخ پیام دستگاه، یا فراتر رفتن از سهمیه نرخ پیام موضوعی باشد. نرخ پیام بیش از حد است : نرخ ارسال پیام ها بسیار بالا است. شما باید نرخ کلی ارسال پیام را کاهش دهید. از عقب نشینی نمایی با حداقل تاخیر اولیه 1 دقیقه برای امتحان مجدد پیام های رد شده استفاده کنید. نرخ پیام دستگاه بیش از حد است : نرخ پیامها به یک دستگاه خاص بسیار زیاد است. محدودیت نرخ پیام برای یک دستگاه را ببینید . تعداد پیامهای ارسال شده به این دستگاه را کاهش دهید و برای ارسال مجدد از عقبنشینی نمایی استفاده کنید. نرخ پیام موضوع بیش از حد : نرخ پیام به مشترکین یک موضوع خاص بسیار زیاد است. تعداد پیامهای ارسالشده برای این موضوع را کاهش دهید و برای ارسال مجدد از عقبنشینی نمایی با حداقل تأخیر اولیه ۱ دقیقه استفاده کنید. |
UNAVAILABLE (کد خطای HTTP = 503) سرور بیش از حد بارگیری شده است. | سرور نتوانست به موقع درخواست را پردازش کند. همان درخواست را دوباره امتحان کنید، اما باید: - اگر هدر Retry-After در پاسخ سرور اتصال FCM گنجانده شده است، به آن احترام بگذارید. - در مکانیسم تلاش مجدد خود، عقب نشینی نمایی را پیاده سازی کنید. (مثلاً اگر یک ثانیه قبل از اولین تلاش مجدد صبر کرده اید، حداقل دو ثانیه قبل از امتحان بعدی صبر کنید، سپس 4 ثانیه و غیره). اگر چندین پیام ارسال میکنید، از جیترینگ استفاده کنید. برای کسب اطلاعات بیشتر، به مدیریت تلاش های مجدد مراجعه کنید . فرستنده هایی که مشکل ایجاد می کنند، در معرض خطر رد شدن هستند. |
INTERNAL (کد خطای HTTP = 500) یک خطای داخلی ناشناخته رخ داد. | سرور هنگام تلاش برای پردازش درخواست با خطایی مواجه شد. میتوانید همان درخواست را پس از پیشنهادات موجود در «کنترل تلاشهای مجدد» دوباره امتحان کنید . اگر خطا ادامه داشت، لطفاً با پشتیبانی Firebase تماس بگیرید. |
THIRD_PARTY_AUTH_ERROR (کد خطای HTTP = 401) گواهینامه APN یا کلید تأیید وب فشار نامعتبر یا گم شده بود. | پیامی که برای یک دستگاه iOS یا ثبت نام فشار وب ارسال شده است ارسال نشد. اعتبار اعتبارنامه توسعه و تولید خود را بررسی کنید. |
کدهای خطای مدیریت
جدول زیر کدهای خطای Firebase Admin FCM API و توضیحات آنها، از جمله مراحل وضوح پیشنهادی را فهرست میکند.
کد خطا | مراحل شرح و تفکیک |
---|---|
messaging/invalid-argument | یک آرگومان نامعتبر به روش FCM ارائه شد. پیام خطا باید حاوی اطلاعات اضافی باشد. |
messaging/invalid-recipient | گیرنده پیام مورد نظر نامعتبر است. پیام خطا باید حاوی اطلاعات اضافی باشد. |
messaging/invalid-payload | یک شیء محموله پیام نامعتبر ارائه شد. پیام خطا باید حاوی اطلاعات اضافی باشد. |
messaging/invalid-data-payload-key | محموله پیام داده حاوی یک کلید نامعتبر است. به مستندات مرجع DataMessagePayload برای کلیدهای محدود مراجعه کنید. |
messaging/payload-size-limit-exceeded | محموله پیام ارائه شده از محدودیت های اندازه FCM بیشتر است. محدودیت برای اکثر پیام ها 4096 بایت است. برای پیام های ارسال شده به موضوعات، محدودیت 2048 بایت است. اندازه کل محموله شامل کلیدها و مقادیر است. |
messaging/invalid-options | یک شیء گزینه های پیام نامعتبر ارائه شد. پیام خطا باید حاوی اطلاعات اضافی باشد. |
messaging/invalid-registration-token | رمز ثبت نام معتبر ارائه شده است. مطمئن شوید که با نشانه ثبتی که برنامه مشتری از ثبت نام در FCM دریافت می کند مطابقت دارد. از کوتاه کردن یا اضافه کردن کاراکترهای اضافی به آن خودداری کنید. |
messaging/registration-token-not-registered | رمز ثبت نام ارائه شده ثبت نشده است. نشانه ثبت نام معتبر قبلی به دلایل مختلفی می تواند لغو ثبت شود، از جمله:
|
messaging/invalid-package-name | این پیام به نشانه ثبت نامی که نام بسته آن با گزینه restrictedPackageName ارائه شده مطابقت ندارد، خطاب شده است. |
messaging/message-rate-exceeded | نرخ پیام به یک هدف خاص بسیار بالا است. تعداد پیام های ارسال شده به این دستگاه یا موضوع را کاهش دهید و فوراً ارسال مجدد به این هدف را تکرار نکنید. |
messaging/device-message-rate-exceeded | نرخ پیام به یک دستگاه خاص بسیار بالا است. تعداد پیام های ارسال شده به این دستگاه را کاهش دهید و فوراً ارسال مجدد به این دستگاه را تکرار نکنید. |
messaging/topics-message-rate-exceeded | نرخ پیام به مشترکین یک موضوع خاص بسیار زیاد است. تعداد پیام های ارسال شده برای این موضوع را کاهش دهید و بلافاصله برای ارسال مجدد به این موضوع خودداری کنید. |
messaging/too-many-topics | یک نشانه ثبت نام در حداکثر تعداد موضوع مشترک شده است و دیگر نمی توان در آن مشترک شد. |
messaging/invalid-apns-credentials | پیامی که برای دستگاه Apple مورد هدف قرار گرفته است ارسال نشد زیرا گواهینامه SSL APN های مورد نیاز آپلود نشده یا منقضی شده است. اعتبار گواهی های توسعه و تولید خود را بررسی کنید. |
messaging/mismatched-credential | اعتبار مورد استفاده برای احراز هویت این SDK مجوز ارسال پیام به دستگاه مربوط به رمز ثبت نام ارائه شده را ندارد. اطمینان حاصل کنید که اعتبار و رمز ثبت نام هر دو متعلق به یک پروژه Firebase هستند. برای مستندات مربوط به نحوه احراز هویت Firebase Admin SDK s ، به افزودن Firebase به برنامه خود مراجعه کنید. |
messaging/authentication-error | SDK نمی تواند در سرورهای FCM احراز هویت شود. اطمینان حاصل کنید که Firebase Admin SDK با اعتباری که دارای مجوزهای مناسب برای ارسال پیام های FCM است، احراز هویت کنید. برای مستندات مربوط به نحوه احراز هویت Firebase Admin SDK s ، به افزودن Firebase به برنامه خود مراجعه کنید. |
messaging/server-unavailable | سرور FCM نتوانست درخواست را به موقع پردازش کند. شما باید همان درخواست را دوباره امتحان کنید، اما باید:
|
messaging/internal-error | سرور FCM هنگام تلاش برای پردازش درخواست با خطا مواجه شد. میتوانید با پیروی از الزامات ذکر شده در ردیف messaging/server-unavailable همان درخواست را دوباره امتحان کنید. اگر خطا ادامه داشت، لطفاً مشکل را به کانال پشتیبانی گزارش اشکال ما گزارش دهید. |
messaging/unknown-error | یک خطای سرور ناشناخته برگردانده شد. برای جزئیات بیشتر، پاسخ سرور خام را در پیام خطا مشاهده کنید. اگر این خطا را دریافت کردید، لطفاً پیام خطای کامل را به کانال پشتیبانی گزارش اشکال ما گزارش دهید. |
با استفاده از پروتکلهای سرور برنامه قدیمی پیامها را ارسال کنید
اگر در حال حاضر از پروتکل های قدیمی استفاده می کنید، درخواست های پیام را همانطور که در این بخش نشان داده شده است ایجاد کنید. به خاطر داشته باشید که اگر از طریق HTTP به چندین پلتفرم ارسال می کنید، پروتکل v1 می تواند درخواست های پیام شما را تا حد زیادی ساده کند.
ارسال پیام به دستگاه های خاص
برای ارسال پیام به دستگاههای خاص، کلید to
را روی نشانه ثبتنام برای نمونه برنامه خاص تنظیم کنید. برای کسب اطلاعات بیشتر در مورد نشانه های ثبت نام، اطلاعات راه اندازی مشتری را برای پلتفرم خود مشاهده کنید.
درخواست HTTP POST
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..."
}
پاسخ HTTP
{ "multicast_id": 108, "success": 1, "failure": 0, "results": [ { "message_id": "1:08" } ] }
پیام XMPP
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
پاسخ XMPP
<message id=""> <gcm xmlns="google:mobile:data"> { "from":"REGID", "message_id":"m-1366082849205" "message_type":"ack" } </gcm> </message>
سرور اتصال XMPP گزینه های دیگری را برای پاسخ ها فراهم می کند. فرمت پاسخ سرور را ببینید.
برای فهرست کامل گزینههای پیام موجود هنگام ارسال پیامهای پاییندستی به برنامههای مشتری، به اطلاعات مرجع پروتکل سرور اتصال انتخابی خود، HTTP یا XMPP مراجعه کنید.
ارسال پیام به موضوعات
ارسال پیام به یک موضوع Firebase Cloud Messaging بسیار شبیه به ارسال پیام به یک دستگاه یا یک گروه کاربری است. سرور برنامه to
با مقداری مانند /topics/yourTopic
تنظیم می کند. برنامهنویسان میتوانند هر نام موضوعی را که با عبارت معمولی مطابقت دارد انتخاب کنند: "/topics/[a-zA-Z0-9-_.~%]+"
.
برای ارسال به ترکیبی از چندین موضوع، سرور برنامه باید کلید condition
(به جای کلید to
) را روی یک شرط بولی تنظیم کند که موضوعات مورد نظر را مشخص می کند. به عنوان مثال، برای ارسال پیام به دستگاههایی که مشترک TopicA
و TopicB
یا TopicC
هستند:
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
FCM ابتدا هر شرایط داخل پرانتز را ارزیابی می کند و سپس عبارت را از چپ به راست ارزیابی می کند. در عبارت بالا، کاربری که در یک موضوع مشترک است، پیامی را دریافت نمی کند. به همین ترتیب، کاربری که در TopicA مشترک نمی شود، پیام را دریافت نمی کند. این ترکیب ها آن را دریافت می کنند:
- TopicA و TopicB
- موضوع A و موضوع C
می توانید حداکثر پنج موضوع را در عبارت شرطی خود بگنجانید و پرانتزها پشتیبانی می شوند. اپراتورهای پشتیبانی شده: &&
، ||
.
موضوع درخواست HTTP POST
ارسال به یک موضوع:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
ارسال به دستگاههایی که در موضوعات «سگ» یا «گربه» مشترک شدهاند:
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
پاسخ HTTP موضوع
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
موضوع پیام XMPP
ارسال به یک موضوع:
<message id="">
<gcm xmlns="google:mobile:data">
</gcm>
</message>
ارسال به دستگاههایی که در موضوعات «سگ» یا «گربه» مشترک شدهاند:
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
پاسخ موضوع XMPP
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
قبل از اینکه سرور FCM یک پاسخ موفقیت آمیز یا ناموفق را به درخواست های ارسال موضوع ارسال کند، تا 30 ثانیه تاخیر انتظار داشته باشید. مطمئن شوید که مقدار مهلت زمانی سرور برنامه را در درخواست تنظیم کرده اید.
ارسال پیام به گروه های دستگاه
ارسال پیام به یک گروه دستگاه با استفاده از APIهای قدیمی قدیمی بسیار شبیه به ارسال پیام به یک دستگاه جداگانه است. پارامتر to
روی کلید اعلان یکتا برای گروه دستگاه تنظیم کنید. مثالهای این بخش نحوه ارسال پیامهای داده به گروههای دستگاه در پروتکلهای قدیمی HTTP و XMPP را نشان میدهد.
درخواست HTTP POST گروه دستگاه
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!", } }
پاسخ HTTP گروه دستگاه
در اینجا یک مثال از "موفقیت" آمده است - notification_key
دارای 2 نشانه ثبت نام مرتبط با آن است و پیام با موفقیت برای هر دوی آنها ارسال شد:
{ "success": 2, "failure": 0 }
در اینجا یک مثال از "موفقیت جزئی" آورده شده است - notification_key
دارای 3 نشانه ثبت نام مرتبط با آن است. پیام فقط به 1 نشانه ثبت نام با موفقیت ارسال شد. پیام پاسخ، نشانههای ثبت نام ( registration_ids
) را که موفق به دریافت پیام نشدهاند، فهرست میکند:
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
هنگامی که پیامی به یک یا چند نشانه ثبت نام مرتبط با یک notification_key
تحویل داده نمیشود، سرور برنامه باید با پشتیبان بین تلاشهای مجدد، مجدداً تلاش کند.
اگر سرور بخواهد پیامی را به گروه دستگاهی که هیچ عضوی ندارد ارسال کند، پاسخ به شکل زیر است، با 0 موفقیت و 0 شکست:
{ "success": 0, "failure": 0 }
پیام XMPP گروه دستگاه
<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>
پاسخ XMPP گروه دستگاه
هنگامی که پیام با موفقیت به یکی از دستگاه های گروه ارسال می شود، سرور اتصال XMPP با یک ACK پاسخ می دهد. اگر همه پیامهای ارسال شده به همه دستگاههای گروه ناموفق باشند، سرور اتصال XMPP با NACK پاسخ میدهد.
در اینجا یک مثال از "موفقیت" آمده است - notification_key
دارای 3 نشانه ثبت نام مرتبط با آن است و پیام با موفقیت برای همه آنها ارسال شد:
{ "from": "aUniqueKey", "message_type": "ack", "success": 3, "failure": 0, "message_id": "m-1366082849205" }
در اینجا یک مثال از "موفقیت جزئی" آمده است - notification_key
دارای 3 نشانه ثبت نام مرتبط با آن است. پیام فقط به یکی از نشانه های ثبت نام با موفقیت ارسال شد. پیام پاسخ، نشانه های ثبت نامی را که پیام را دریافت نکرده اند فهرست می کند:
{ "from": "aUniqueKey", "message_type": "ack", "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
وقتی سرور اتصال FCM نتواند به همه دستگاههای گروه تحویل دهد. سرور برنامه یک پاسخ ناک دریافت خواهد کرد.
برای لیست کامل گزینه های پیام، اطلاعات مرجع پروتکل سرور اتصال انتخابی خود، HTTP یا XMPP را ببینید.
روشهای ارسال قدیمی Firebase Admin SDK
Firebase Admin Node.js SDK از روش هایی برای ارسال پیام ( FCM ) بر اساس API سرور FCM Legacy پشتیبانی می کند. این متدها آرگومان های متفاوتی را در مقایسه با متد send()
می پذیرند. شما باید در صورت امکان از متد send()
استفاده کنید و فقط هنگام ارسال پیام به دستگاهها یا گروههای دستگاه از روشهای توضیح داده شده در این صفحه استفاده کنید.
ارسال به دستگاه های فردی
می توانید یک رمز ثبت نام را به متد sendToDevice()
برای ارسال پیام به آن دستگاه ارسال کنید:
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);
});
متد sendToDevice()
همچنین میتواند یک پیام چندپخشی (یعنی یک پیام به چندین دستگاه) را با ارسال یک آرایه از نشانههای ثبت به جای تنها یک نشانه ثبت ارسال کند:
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);
});
متد sendToDevice()
وعده ای را برمی گرداند که با یک شی MessagingDevicesResponse
حاوی پاسخ FCM حل می شود. نوع برگشتی در هنگام ارسال یک نشانه ثبت نام واحد یا آرایه ای از نشانه های ثبت، فرمت یکسانی دارد.
برخی از موارد مانند خطای احراز هویت یا محدود کردن نرخ باعث می شود که کل پیام پردازش نشود. در این موارد، وعده بازگشتی توسط sendToDevice()
با خطا رد می شود. برای فهرست کامل کدهای خطا، از جمله توضیحات و مراحل حل، به Admin FCM API Errors مراجعه کنید.
ارسال به گروه دستگاه
متد sendToDeviceGroup()
به شما این امکان را می دهد که با تعیین کلید اعلان برای آن گروه دستگاه پیامی را به گروه دستگاه ارسال کنید:
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);
});
متد sendToDeviceGroup()
وعده ای را برمی گرداند که با یک شی MessagingDevicesResponse
حاوی پاسخ FCM حل می شود.
برخی از موارد مانند خطای احراز هویت یا محدود کردن نرخ باعث می شود که کل پیام پردازش نشود. در این موارد، وعده بازگشتی توسط sendToDeviceGroup()
با خطا رد می شود. برای فهرست کامل کدهای خطا، از جمله توضیحات و مراحل حل، به Admin FCM API Errors مراجعه کنید.
تعریف محموله پیام
روش های فوق بر اساس پروتکل های قدیمی FCM یک بار پیام را به عنوان آرگومان دوم خود می پذیرند و از پیام های اطلاع رسانی و داده پشتیبانی می کنند. شما می توانید یک یا هر دو نوع پیام را با ایجاد یک شی با کلیدهای data
و/یا notification
مشخص کنید. برای مثال، در اینجا نحوه تعریف انواع مختلف بارهای پیام آورده شده است:
پیام اعلان
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.'
}
};
پیام داده
const payload = {
data: {
score: '850',
time: '2:45'
}
};
پیام ترکیبی
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'
}
};
محمولههای پیام اعلان دارای زیرمجموعهای از ویژگیهای معتبر از پیش تعریفشده هستند و بسته به اینکه کدام سیستم عامل موبایلی را هدف قرار میدهید، کمی متفاوت است. برای فهرست کامل به اسناد مرجع برای NotificationMessagePayload
مراجعه کنید.
بارهای پیام داده از جفت های کلید-مقدار سفارشی با چند محدودیت تشکیل شده اند، از جمله این واقعیت که همه مقادیر باید رشته ای باشند. برای مشاهده لیست کامل محدودیت ها به اسناد مرجع DataMessagePayload
مراجعه کنید.
تعریف گزینه های پیام
روشهای فوق مبتنی بر پروتکلهای قدیمی FCM آرگومان سوم اختیاری را میپذیرند که برخی از گزینهها را برای پیام مشخص میکند. به عنوان مثال، مثال زیر یک پیام با اولویت بالا به دستگاهی ارسال می کند که پس از 24 ساعت منقضی می شود:
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);
});
برای لیست کامل گزینه های موجود، به اسناد مرجع برای MessagingOptions
مراجعه کنید.