Check out what’s new from Firebase at Google I/O 2022. Learn more

בניית בקשות שליחת שרת אפליקציות

באמצעות פרוטוקולי שרת האפליקציות של Firebase Admin או FCM, אתה יכול לבנות בקשות הודעות ולשלוח אותן לסוגים אלה של יעדים:

  • שם הנושא
  • מַצָב
  • אסימון רישום מכשיר
  • שם קבוצת מכשירים (פרוטוקולים מדור קודם ו-SDK Admin של Firebase עבור Node.js בלבד)

אתה יכול לשלוח הודעות עם מטען הודעות המורכב משדות מוגדרים מראש, מטען נתונים של שדות המוגדרים על ידי המשתמש שלך, או הודעה המכילה את שני סוגי המטען. ראה סוגי הודעות למידע נוסף.

דוגמאות בדף זה מראות כיצד לשלוח הודעות התראה באמצעות 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);
  });

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);

פִּיתוֹן

# 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)

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);

מנוחה

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 מחזיר את מחרוזת המזהה בפורמט projects/{project_id}/messages/{message_id} . תגובת פרוטוקול HTTP היא מפתח JSON יחיד:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

שלח הודעות למספר מכשירים

ממשקי ה-API של REST וממשקי ה-API של Admin FCM מאפשרים לך לשדר הודעה מרובה לרשימה של אסימוני רישום מכשיר. אתה יכול לציין עד 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');
  });

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");

פִּיתוֹן

# 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)

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.SendMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");

מנוחה

בנה בקשת אצווה HTTP:

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message!"
     }
  }
}

...

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message!"
     }
  }
}
--subrequest_boundary--

שמור את הבקשה בקובץ (בדוגמה זו batch_request.txt). לאחר מכן השתמש בפקודה cURL:

curl --data-binary @batch_request.txt -H 'Content-Type: multipart/mixed; boundary="subrequest_boundary"' https://fcm.googleapis.com/batch

עבור Firebase Admin SDKs, פעולה זו משתמשת בממשק ה-API sendAll() מתחת למכסה המנוע, כפי שמוצג בדוגמאות. ערך ההחזרה הוא BatchResponse שרשימת התגובות שלו מתאימה לסדר אסימוני הקלט. זה שימושי כאשר אתה רוצה לבדוק אילו אסימונים הובילו לשגיאות.

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);
}

פִּיתוֹן

# 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)
}

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.SendMulticastAsync(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}");
}

מנוחה

כל שליחה משנה מחזירה תגובה. תגובות מופרדות על ידי מחרוזת גבול תגובה המתחילה --batch_ .

--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q
Content-Type: application/http
Content-ID: response-

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{
  "name": "projects/35006771263/messages/0:1570471792141125%43c11b7043c11b70"
}

...

--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q
Content-Type: application/http
Content-ID: response-

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{
  "name": "projects/35006771263/messages/0:1570471792141696%43c11b7043c11b70"
}

--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q--

שלח הודעות לנושאים

לאחר שיצרת נושא, או על ידי הרשמה למופעי אפליקציית לקוח לנושא בצד הלקוח או באמצעות ממשק ה-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);
  });

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);

פִּיתוֹן

# 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)

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);

מנוחה

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);
  });

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);

פִּיתוֹן

# 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)

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);

מנוחה

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

שלח קבוצה של הודעות

REST API ו-SDK של Admin תומכים בשליחת הודעות באצווה. אתה יכול לקבץ עד 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');
  });

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");

פִּיתוֹן

# 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)

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.SendAllAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");

מנוחה

בנה בקשת אצווה HTTP על ידי שילוב של רשימה של בקשות משנה:

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message to device 0!"
     }
  }
}

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "topic":"readers-club",
     "notification":{
       "title":"Price drop",
       "body":"2% off all books"
     }
  }
}

...

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message to device N!"
     }
  }
}
--subrequest_boundary--

אתה יכול לשאול את BatchResponse שהוחזר כדי לבדוק כמה מההודעות נמסרו ל-FCM בהצלחה. זה גם חושף רשימה של תגובות שניתן להשתמש בהן כדי לבדוק את מצבן של הודעות בודדות. סדר התגובות מתאים לסדר ההודעות ברשימת הקלט.

שלח הודעות התומכות באתחול ישיר (אנדרואיד בלבד)

אתה יכול לשלוח הודעות למכשירים במצב אתחול ישיר באמצעות HTTP v1 או HTTP API מדור קודם. לפני שליחה למכשירים במצב אתחול ישיר, ודא שהשלמת את השלבים כדי לאפשר למכשירי לקוח לקבל הודעות 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,
    },
}

שלח באמצעות FCM HTTP API מדור קודם

בקשת ההודעה חייבת לכלול את המפתח "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 ופרוטוקול HTTP v1 FCM מאפשרים לבקשות ההודעה שלך להגדיר את כל השדות הזמינים באובייקט message . זה כולל:

  • קבוצה משותפת של שדות שיתפרשו על ידי כל מופעי האפליקציה שמקבלים את ההודעה.
  • קבוצות שדות ספציפיות לפלטפורמה, כגון AndroidConfig ו- WebpushConfig , המתפרשות רק על ידי מופעי אפליקציה הפועלים בפלטפורמה שצוינה.

בלוקים ספציפיים לפלטפורמה נותנים לך גמישות להתאים אישית הודעות עבור פלטפורמות שונות כדי להבטיח שהן מטופלות בצורה נכונה בעת קבלתן. ה-backend של FCM ייקח בחשבון את כל הפרמטרים שצוינו ויתאים אישית את ההודעה לכל פלטפורמה.

מתי להשתמש בשדות נפוצים

השתמש בשדות נפוצים כאשר אתה:

  • מיקוד למופעי אפליקציות בכל הפלטפורמות - אפל, אנדרואיד ואינטרנט
  • שליחת הודעות לנושאים

כל מופעי האפליקציה, ללא קשר לפלטפורמה, יכולים לפרש את השדות הנפוצים הבאים:

מתי להשתמש בשדות ספציפיים לפלטפורמה

השתמש בשדות ספציפיים לפלטפורמה כאשר אתה רוצה:

  • שלח שדות רק לפלטפורמות מסוימות
  • שלח שדות ספציפיים לפלטפורמה בנוסף לשדות הנפוצים

בכל פעם שאתה רוצה לשלוח ערכים רק לפלטפורמות מסוימות, אל תשתמש בשדות נפוצים; להשתמש בשדות ספציפיים לפלטפורמה. לדוגמה, כדי לשלוח הודעה רק לפלטפורמות ולאינטרנט של Apple אך לא לאנדרואיד, עליך להשתמש בשתי קבוצות נפרדות של שדות, אחת לאפל ואחת לאינטרנט.

כאשר אתה שולח הודעות עם אפשרויות מסירה ספציפיות, השתמש בשדות ספציפיים לפלטפורמה כדי להגדיר אותן. אתה יכול לציין ערכים שונים לכל פלטפורמה אם תרצה. עם זאת, גם כאשר אתה רוצה להגדיר בעצם אותו ערך על פני פלטפורמות, עליך להשתמש בשדות ספציפיים לפלטפורמה. הסיבה לכך היא שכל פלטפורמה עשויה לפרש את הערך בצורה מעט שונה - לדוגמה, זמן חיים מוגדר באנדרואיד כזמן תפוגה בשניות, בעוד שב-Apple הוא מוגדר כתאריך תפוגה.

דוגמה: הודעת התראה עם אפשרויות צבע וסמלים

בקשת שליחת דוגמה זו שולחת כותרת הודעה ותוכן משותפים לכל הפלטפורמות, אך היא גם שולחת כמה דחיקות ספציפיות לפלטפורמה למכשירי אנדרואיד.

עבור אנדרואיד, הבקשה מגדירה סמל וצבע מיוחדים שיוצגו במכשירי אנדרואיד. כפי שצוין בהפניה ל- 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);
  });

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();

פִּיתוֹן

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",
}

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",
};

מנוחה

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 לקבלת פרטים מלאים על המפתחות הזמינים בלוקים ספציפיים לפלטפורמה בגוף ההודעה.

קודי שגיאה של מנהל מערכת

הטבלה הבאה מפרטת את קודי השגיאה של 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 אסימון הרישום שסופק אינו רשום. ניתן לבטל רישום של אסימון רישום תקף בעבר ממגוון סיבות, כולל:
  • אפליקציית הלקוח ביטלה את עצמה מ-FCM.
  • אפליקציית הלקוח בוטלה באופן אוטומטי. זה יכול לקרות אם המשתמש מסיר את ההתקנה של האפליקציה או, בפלטפורמות של Apple, אם שירות המשוב של ה-APN דיווח על אסימון ה-APN כלא חוקי.
  • פג תוקף אסימון הרישום. לדוגמה, גוגל עשויה להחליט לרענן אסימוני רישום או שאסימון APNs פג עבור מכשירי אפל.
  • אפליקציית הלקוח עודכנה, אך הגרסה החדשה אינה מוגדרת לקבל הודעות.
בכל המקרים הללו, הסר אסימון רישום זה והפסק להשתמש בו לשליחת הודעות.
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 לא ניתן לשלוח הודעה המיועדת למכשיר אפל מכיוון שאישור ה-SSL של APNs הנדרש לא הועלה או שפג תוקפו. בדוק את תוקף תעודות הפיתוח והייצור שלך.
messaging/mismatched-credential לאישור המשמש לאימות SDK זה אין הרשאה לשלוח הודעות למכשיר התואמות לאסימון הרישום שסופק. ודא שהאישור ואסימון הרישום שייכים שניהם לאותו פרויקט Firebase. ראה הוסף Firebase לאפליקציה שלך לתיעוד על אופן האימות של Firebase Admin SDKs.
messaging/authentication-error ה-SDK לא הצליח לבצע אימות לשרתי FCM. ודא שאתה מאמת את Firebase Admin SDK עם אישור בעל ההרשאות המתאימות לשלוח הודעות FCM. ראה הוסף Firebase לאפליקציה שלך לתיעוד על אופן האימות של Firebase Admin SDKs.
messaging/server-unavailable שרת FCM לא הצליח לעבד את הבקשה בזמן. עליך לנסות שוב את אותה בקשה, אך עליך:
  • כבד את הכותרת Retry-After אם היא כלולה בתגובה משרת החיבורים של 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 ו- TopicC

אתה יכול לכלול עד חמישה נושאים בביטוי המותנה שלך, וסוגריים נתמכים. אופרטורים נתמכים: && , || .

בקשת 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"
}

צפה של עיכוב של עד 30 שניות לפני ששרת FCM יחזיר תגובת הצלחה או כישלון לבקשות שליחת הנושא. הקפד להגדיר את ערך הזמן הקצוב של שרת האפליקציה בבקשה בהתאם.

שלח הודעות לקבוצות מכשירים

שליחת הודעות לקבוצת מכשירים דומה מאוד לשליחת הודעות למכשיר בודד. הגדר את הפרמטר 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 אסימוני רישום המשויכים אליו. ההודעה נשלחה בהצלחה לאחד מאסימוני הרישום בלבד. הודעת התגובה מפרטת את אסימוני הרישום ( 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 לא מצליח לספק לכל המכשירים בקבוצה. שרת האפליקציה יקבל תגובת Nack.

לרשימה המלאה של אפשרויות ההודעה, עיין במידע ההפניה עבור פרוטוקול שרת החיבור שבחרת, HTTP או XMPP .

שיטות שליחת Firebase Admin SDK מדור קודם

Firebase Admin Node.js SDK תומך בשיטות לשליחת הודעות (FCM) המבוססות על ה-API של שרת FCM מדור קודם . שיטות אלו מקבלות ארגומנטים שונים בהשוואה לשיטת 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 .

שלח לקבוצת מכשירים

הודעות קבוצת מכשירים מאפשרות לך להוסיף מספר מכשירים לקבוצה אחת. זה דומה להעברת הודעות בנושא, אבל כולל אימות כדי להבטיח שהחברות בקבוצה מנוהלת רק על ידי השרתים שלך. לדוגמה, אם אתה רוצה לשלוח הודעות שונות לדגמי טלפון שונים, השרתים שלך יכולים להוסיף/להסיר רישומים לקבוצות המתאימות ולשלוח את ההודעה המתאימה לכל קבוצה. העברת הודעות בקבוצת מכשירים שונה מהעברת הודעות בנושא בכך שהיא כוללת ניהול קבוצות מכשירים מהשרתים שלך במקום ישירות בתוך האפליקציה שלך.

אתה יכול להשתמש בהודעות קבוצת מכשירים באמצעות פרוטוקולי XMPP או HTTP מדור קודם בשרת האפליקציות שלך. גרסאות ישנות יותר של Firebase Admin SDK עבור Node.js מבוססות על הפרוטוקולים מדור קודם ומספקות גם יכולות העברת הודעות בקבוצות מכשירים. המספר המרבי של חברים המותר למפתח הודעה הוא 20.

אתה יכול ליצור קבוצות מכשירים וליצור מפתחות התראות דרך שרת אפליקציות או לקוח אנדרואיד. ראה ניהול קבוצות מכשירים לפרטים.

שיטת 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 לקבלת רשימה מלאה של אפשרויות זמינות.

,

באמצעות פרוטוקולי שרת האפליקציות של Firebase Admin או FCM, אתה יכול לבנות בקשות הודעות ולשלוח אותן לסוגים אלה של יעדים:

  • שם הנושא
  • מַצָב
  • אסימון רישום מכשיר
  • שם קבוצת מכשירים (פרוטוקולים מדור קודם ו-SDK Admin של Firebase עבור Node.js בלבד)

אתה יכול לשלוח הודעות עם מטען הודעות המורכב משדות מוגדרים מראש, מטען נתונים של שדות המוגדרים על ידי המשתמש שלך, או הודעה המכילה את שני סוגי המטען. ראה סוגי הודעות למידע נוסף.

דוגמאות בדף זה מראות כיצד לשלוח הודעות התראה באמצעות 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);
  });

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);

פִּיתוֹן

# 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)

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);

מנוחה

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 מחזיר את מחרוזת המזהה בפורמט projects/{project_id}/messages/{message_id} . תגובת פרוטוקול HTTP היא מפתח JSON יחיד:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

שלח הודעות למספר מכשירים

ממשקי ה-API של REST וממשקי ה-API של Admin FCM מאפשרים לך לשדר הודעה מרובה לרשימה של אסימוני רישום מכשיר. אתה יכול לציין עד 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');
  });

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");

פִּיתוֹן

# 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)

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.SendMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");

מנוחה

בנה בקשת אצווה HTTP:

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message!"
     }
  }
}

...

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message!"
     }
  }
}
--subrequest_boundary--

שמור את הבקשה בקובץ (בדוגמה זו batch_request.txt). לאחר מכן השתמש בפקודה cURL:

curl --data-binary @batch_request.txt -H 'Content-Type: multipart/mixed; boundary="subrequest_boundary"' https://fcm.googleapis.com/batch

עבור Firebase Admin SDKs, פעולה זו משתמשת בממשק ה-API sendAll() מתחת למכסה המנוע, כפי שמוצג בדוגמאות. ערך ההחזרה הוא BatchResponse שרשימת התגובות שלו מתאימה לסדר אסימוני הקלט. זה שימושי כאשר אתה רוצה לבדוק אילו אסימונים הובילו לשגיאות.

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);
}

פִּיתוֹן

# 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)
}

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.SendMulticastAsync(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}");
}

מנוחה

כל שליחת משנה שליחה מחזירה תגובה. תגובות מופרדות על ידי מחרוזת גבול תגובה המתחילה --batch_ .

--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q
Content-Type: application/http
Content-ID: response-

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{
  "name": "projects/35006771263/messages/0:1570471792141125%43c11b7043c11b70"
}

...

--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q
Content-Type: application/http
Content-ID: response-

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{
  "name": "projects/35006771263/messages/0:1570471792141696%43c11b7043c11b70"
}

--batch_nDhMX4IzFTDLsCJ3kHH7v_44ua-aJT6q--

שלח הודעות לנושאים

לאחר שיצרת נושא, או על ידי הרשמה למופעי אפליקציית לקוח לנושא בצד הלקוח או באמצעות ממשק ה-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);
  });

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);

פִּיתוֹן

# 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)

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);

מנוחה

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);
  });

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);

פִּיתוֹן

# 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)

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);

מנוחה

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

שלח קבוצה של הודעות

REST API ו-SDK של Admin תומכים בשליחת הודעות באצווה. אתה יכול לקבץ עד 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');
  });

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");

פִּיתוֹן

# 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)

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.SendAllAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");

מנוחה

בנה בקשת אצווה HTTP על ידי שילוב של רשימה של בקשות משנה:

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message to device 0!"
     }
  }
}

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "topic":"readers-club",
     "notification":{
       "title":"Price drop",
       "body":"2% off all books"
     }
  }
}

...

--subrequest_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

POST /v1/projects/myproject-b5ae1/messages:send
Content-Type: application/json
accept: application/json

{
  "message":{
     "token":"cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
     "notification":{
       "title":"FCM Message",
       "body":"This is an FCM notification message to device N!"
     }
  }
}
--subrequest_boundary--

אתה יכול לשאול את BatchResponse שהוחזר כדי לבדוק כמה מההודעות נמסרו ל-FCM בהצלחה. זה גם חושף רשימה של תגובות שניתן להשתמש בהן כדי לבדוק את מצבן של הודעות בודדות. סדר התגובות מתאים לסדר ההודעות ברשימת הקלט.

שלח הודעות התומכות באתחול ישיר (אנדרואיד בלבד)

אתה יכול לשלוח הודעות למכשירים במצב אתחול ישיר באמצעות HTTP v1 או HTTP API מדור קודם. לפני שליחה למכשירים במצב אתחול ישיר, ודא שהשלמת את השלבים כדי לאפשר למכשירי לקוח לקבל הודעות 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,
    },
}

שלח באמצעות FCM HTTP API מדור קודם

בקשת ההודעה חייבת לכלול את המפתח "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 ופרוטוקול HTTP v1 FCM מאפשרים לבקשות ההודעה שלך להגדיר את כל השדות הזמינים באובייקט message . זה כולל:

  • קבוצה משותפת של שדות שיתפרשו על ידי כל מופעי האפליקציה שמקבלים את ההודעה.
  • קבוצות שדות ספציפיות לפלטפורמה, כגון AndroidConfig ו- WebpushConfig , המתפרשות רק על ידי מופעי אפליקציה הפועלים בפלטפורמה שצוינה.

בלוקים ספציפיים לפלטפורמה נותנים לך גמישות להתאים אישית הודעות עבור פלטפורמות שונות כדי להבטיח שהן מטופלות בצורה נכונה בעת קבלתן. ה-backend של FCM ייקח בחשבון את כל הפרמטרים שצוינו ויתאים אישית את ההודעה לכל פלטפורמה.

מתי להשתמש בשדות נפוצים

השתמש בשדות נפוצים כאשר אתה:

  • מיקוד למופעי אפליקציות בכל הפלטפורמות - אפל, אנדרואיד ואינטרנט
  • שליחת הודעות לנושאים

כל מופעי האפליקציה, ללא קשר לפלטפורמה, יכולים לפרש את השדות הנפוצים הבאים:

מתי להשתמש בשדות ספציפיים לפלטפורמה

השתמש בשדות ספציפיים לפלטפורמה כאשר אתה רוצה:

  • שלח שדות רק לפלטפורמות מסוימות
  • שלח שדות ספציפיים לפלטפורמה בנוסף לשדות הנפוצים

בכל פעם שאתה רוצה לשלוח ערכים רק לפלטפורמות מסוימות, אל תשתמש בשדות נפוצים; להשתמש בשדות ספציפיים לפלטפורמה. לדוגמה, כדי לשלוח הודעה רק לפלטפורמות ולאינטרנט של Apple אך לא לאנדרואיד, עליך להשתמש בשתי קבוצות נפרדות של שדות, אחת לאפל ואחת לאינטרנט.

כאשר אתה שולח הודעות עם אפשרויות מסירה ספציפיות, השתמש בשדות ספציפיים לפלטפורמה כדי להגדיר אותן. אתה יכול לציין ערכים שונים לכל פלטפורמה אם תרצה. עם זאת, גם כאשר אתה רוצה להגדיר בעצם אותו ערך על פני פלטפורמות, עליך להשתמש בשדות ספציפיים לפלטפורמה. הסיבה לכך היא שכל פלטפורמה עשויה לפרש את הערך בצורה מעט שונה - לדוגמה, זמן חיים מוגדר באנדרואיד כזמן תפוגה בשניות, בעוד שב-Apple הוא מוגדר כתאריך תפוגה.

דוגמה: הודעת התראה עם אפשרויות צבע וסמלים

בקשת שליחת דוגמה זו שולחת כותרת הודעה ותוכן משותפים לכל הפלטפורמות, אך היא גם שולחת כמה דחיקות ספציפיות לפלטפורמה למכשירי אנדרואיד.

עבור אנדרואיד, הבקשה מגדירה סמל וצבע מיוחדים שיוצגו במכשירי אנדרואיד. כפי שצוין בהפניה ל- 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);
  });

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();

פִּיתוֹן

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",
}

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",
};

מנוחה

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 לקבלת פרטים מלאים על המפתחות הזמינים בלוקים ספציפיים לפלטפורמה בגוף ההודעה.

דוגמה: הודעת התראה עם תמונה מותאמת אישית

הדוגמה הבאה של בקשת שליחת שולחת כותרת הודעה משותפת לכל הפלטפורמות, אך היא גם שולחת תמונה. להלן הערכה של האפקט החזותי במכשיר של משתמש:

Simple drawing of an image in a display notification

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);
  });

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"
       }
     }
   }
 }

See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.

Example: notification message with an associated click action

The following example send request sends a common notification title to all platforms, but it also sends an action for the app to perform in response to user interacting with the notification. Here's an approximation of the visual effect on a user's device:

Simple drawing of a user tap opening a web page

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);
  });

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"
       }
     }
   }
 }

See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.

Example: notification message with localization options

The following example send request sends localization options for the client to display localized messages. Here's an approximation of the visual effect on a user's device:

Simple drawing of two devices displaying text in English and Spanish

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);
  });

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"],
                    },
                 },
               },
             },
  },
}'

See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.

Admin error codes

The following table lists the Firebase Admin FCM API error codes and their descriptions, including recommended resolution steps.

Error Code Description and Resolution Steps
messaging/invalid-argument An invalid argument was provided to an FCM method. The error message should contain additional information.
messaging/invalid-recipient The intended message recipient is invalid. The error message should contain additional information.
messaging/invalid-payload An invalid message payload object was provided. The error message should contain additional information.
messaging/invalid-data-payload-key The data message payload contains an invalid key. See the reference documentation for DataMessagePayload for restricted keys.
messaging/payload-size-limit-exceeded The provided message payload exceeds the FCM size limits. The limit is 4096 bytes for most messages. For messages sent to topics, the limit is 2048 bytes. The total payload size includes both keys and values.
messaging/invalid-options An invalid message options object was provided. The error message should contain additional information.
messaging/invalid-registration-token Invalid registration token provided. Make sure it matches the registration token the client app receives from registering with FCM. Do not truncate or add additional characters to it.
messaging/registration-token-not-registered The provided registration token is not registered. A previously valid registration token can be unregistered for a variety of reasons, including:
  • The client app unregistered itself from FCM.
  • The client app was automatically unregistered. This can happen if the user uninstalls the application or, on Apple platforms, if the APNs Feedback Service reported the APNs token as invalid.
  • The registration token expired. For example, Google might decide to refresh registration tokens or the APNs token may have expired for Apple devices.
  • The client app was updated, but the new version is not configured to receive messages.
For all these cases, remove this registration token and stop using it to send messages.
messaging/invalid-package-name The message was addressed to a registration token whose package name does not match the provided restrictedPackageName option.
messaging/message-rate-exceeded The rate of messages to a particular target is too high. Reduce the number of messages sent to this device or topic and do not immediately retry sending to this target.
messaging/device-message-rate-exceeded The rate of messages to a particular device is too high. Reduce the number of messages sent to this device and do not immediately retry sending to this device.
messaging/topics-message-rate-exceeded The rate of messages to subscribers to a particular topic is too high. Reduce the number of messages sent for this topic, and do not immediately retry sending to this topic.
messaging/too-many-topics A registration token has been subscribed to the maximum number of topics and cannot be subscribed to any more.
messaging/invalid-apns-credentials A message targeted to an Apple device could not be sent because the required APNs SSL certificate was not uploaded or has expired. Check the validity of your development and production certificates.
messaging/mismatched-credential The credential used to authenticate this SDK does not have permission to send messages to the device corresponding to the provided registration token. Make sure the credential and registration token both belong to the same Firebase project. See Add Firebase to your app for documentation on how to authenticate the Firebase Admin SDKs.
messaging/authentication-error The SDK could not authenticate to the FCM servers. Make sure you authenticate the Firebase Admin SDK with a credential which has the proper permissions to send FCM messages. See Add Firebase to your app for documentation on how to authenticate the Firebase Admin SDKs.
messaging/server-unavailable The FCM server could not process the request in time. You should retry the same request, but you must:
  • Honor the Retry-After header if it is included in the response from the FCM Connection Server.
  • Implement exponential back-off in your retry mechanism. For example, if you waited one second before the first retry, wait at least two seconds before the next one, then four seconds, and so on. If you're sending multiple messages, delay each one independently by an additional random amount to avoid issuing a new request for all messages at the same time.
Senders that cause problems risk being blacklisted.
messaging/internal-error The FCM server encountered an error while trying to process the request. You could retry the same request following the requirements listed in the messaging/server-unavailable row above. If the error persists, please report the problem to our Bug Report support channel.
messaging/unknown-error An unknown server error was returned. See the raw server response in the error message for more details. If you receive this error, please report the full error message to our Bug Report support channel.

Send messages using the legacy app server protocols

If you prefer to use the legacy protocols, build message requests as shown in this section. Keep in mind that, if you are sending to multiple platforms via HTTP, the v1 protocol can simplify your message requests.

Send messages to specific devices

To send messages to specific devices, set the to key to the registration token for the specific app instance. See the client setup information for your platform to learn more about registration tokens.

HTTP POST request

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 response

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

XMPP message

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

XMPP response

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

The XMPP connection server provides some other options for responses. See Server response format .

For the full list of message options available when sending downstream messages to client apps, see the reference information for your chosen connection server protocol, HTTP or XMPP .

Send messages to topics

Sending messages to a Firebase Cloud Messaging topic is very similar to sending messages to an individual device or to a user group. The app server sets the to key with a value like /topics/yourTopic . Developers can choose any topic name that matches the regular expression: "/topics/[a-zA-Z0-9-_.~%]+" .

To send to combinations of multiple topics, the app server must set the condition key (instead of the to key) to a boolean condition that specifies the target topics. For example, to send messages to devices that subscribed to TopicA and either TopicB or TopicC :

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM first evaluates any conditions in parentheses, and then evaluates the expression from left to right. In the above expression, a user subscribed to any single topic does not receive the message. Likewise, a user who does not subscribe to TopicA does not receive the message. These combinations do receive it:

  • TopicA and TopicB
  • TopicA and TopicC

You can include up to five topics in your conditional expression, and parentheses are supported. Supported operators: && , || .

Topic HTTP POST request

Send to a single topic:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA


Send to devices subscribed to topics "dogs" or "cats":

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA


Topic HTTP response

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Topic XMPP message

Send to a single topic:

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

Send to devices subscribed to topics "dogs" or "cats":

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

Topic XMPP response

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Expect up to 30 seconds of delay before the FCM Server returns a success or failure response to the topic send requests. Make sure to set the app server's timeout value in the request accordingly.

Send messages to device groups

Sending messages to a device group is very similar to sending messages to an individual device. Set the to parameter to the unique notification key for the device group. See Message types for details on payload support. Examples in this page show how to send data messages to device groups in the legacy HTTP and XMPP protocols.

Device Group HTTP POST Request

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!",
   }
}

Device Group HTTP Response

Here is an example of "success"— the notification_key has 2 registration tokens associated with it, and the message was successfully sent to both of them:

{
  "success": 2,
  "failure": 0
}

Here is an example of "partial success" — the notification_key has 3 registration tokens associated with it. The message was successfully sent to 1 of the registration tokens only. The response message lists the registration tokens ( registration_ids ) that failed to receive the message:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

When a message fails to be delivered to one or more of the registration tokens associated with a notification_key , the app server should retry with backoff between retries.

If the server attempts to send a message to a device group that has no members, the response looks like the following, with 0 success and 0 failure:

{
  "success": 0,
  "failure": 0
}

Device Group XMPP Message

<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>

Device Group XMPP Response

When the message is sent to any one of the devices in the group successfully, the XMPP connection server responds with an ACK. If all messages sent to all devices in the group fail, XMPP connection server responds with a NACK.

Here is an example of "success" — the notification_key has 3 registration tokens associated with it, and the message was successfully sent to all of them:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

Here is an example of "partial success" — the notification_key has 3 registration tokens associated with it. The message was successfully sent to 1 of the registration tokens only. The response message lists the registration tokens that failed to receive the message:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

When FCM connection server fails to deliver to all devices in the group. App server will receive a nack response.

For the full list of message options, see the reference information for your chosen connection server protocol, HTTP or XMPP .

Firebase Admin SDK legacy send methods

The Firebase Admin Node.js SDK supports methods for sending (FCM) messages based on the Legacy FCM server API . These methods accept different arguments compared to the send() method. You should use the send() method whenever possible, and only use the methods described in this page when sending messages to individual devices or device groups.

Send to individual devices

You can pass a registration token to the sendToDevice() method to send a message to that device:

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);
  });

The sendToDevice() method can also send a multicast message (that is, a message to multiple devices) by passing an array of registration tokens instead of just a single registration token:

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);
  });

The sendToDevice() method returns a promise that is resolved with a MessagingDevicesResponse object containing the response from FCM. The return type has the same format when passing a single registration token or an array of registration tokens.

Some cases such as an authentication error or rate limiting cause the entirety of the message to fail to process. In these cases, the promise returned by sendToDevice() is rejected with an error. For a full list of error codes, including descriptions and resolution steps, see Admin FCM API Errors .

Send to a device group

Device group messaging allows you to add multiple devices to a single group. This is similar to topic messaging, but includes authentication to ensure that group membership is managed only by your servers. For example, if you want to send different messages to different phone models, your servers can add/remove registrations to the appropriate groups and send the appropriate message to each group. Device group messaging differs from topic messaging in that it involves managing device groups from your servers instead of directly within your application.

You can use device group messaging via the legacy XMPP or HTTP protocols on your app server. Older versions of the Firebase Admin SDK for Node.js are based on the legacy protocols and also provide device group messaging capabilities. The maximum number of members allowed for a notification key is 20.

You can create device groups and generate notification keys via an app server or an Android client. See Managing device groups for details.

The sendToDeviceGroup() method allows you to send a message to a device group by specifying the notification key for that device group:

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);
  });

The sendToDeviceGroup() method returns a promise that is resolved with a MessagingDevicesResponse object containing the response from FCM.

Some cases such as an authentication error or rate limiting cause the entirety of the message to fail to process. In these cases, the promise returned by sendToDeviceGroup() is rejected with an error. For a full list of error codes, including descriptions and resolution steps, see Admin FCM API Errors .

Defining the message payload

The above methods based on the FCM legacy protocols accept a message payload as their second argument and support both notification and data messages . You can specify one or both message types by creating an object with the data and / or notification keys. For example, here is how to define different types of message payloads:

Notification message

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 message

const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

Combined message

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'
  }
};

Notification message payloads have a predefined subset of valid properties and differ slightly depending on which mobile operating system you are targeting. See the reference docs for NotificationMessagePayload for a full list.

Data message payloads are composed of custom key-value pairs with a few restrictions, including the fact that all values must be strings. See the reference docs for DataMessagePayload for a full list of restrictions.

Defining the message options

The above methods based on the FCM legacy protocols accept an optional third argument specifying some options for the message. For example, the following example sends a high priority message to a device which expires after 24 hours:

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);
  });

See the reference docs for MessagingOptions for a full list of available options.