Firebase Admin SDK または FCM アプリサーバーのプロトコルを使用すると、メッセージ リクエストを作成し、それらを次のタイプのターゲットに送信できます。
- トピック名
- 条件
- デバイス登録トークン
- デバイス グループ名(プロトコルのみ)
事前定義フィールドで構成される通知ペイロード、独自のユーザー定義フィールドのデータ ペイロード、またはそれら両方のタイプのペイロードを含むメッセージを使用して、メッセージを送信できます。詳細については、メッセージのタイプを参照してください。
このページの例では、Firebase Admin SDK(Node、Java、Python、C#、Go をサポート)と v1 HTTP プロトコルを使用して通知メッセージを送信する方法を示します。また、非推奨の以前の HTTP および XMPP プロトコルによりメッセージを送信するためのガイダンスもあります。
特定のデバイスにメッセージを送信する
特定の 1 つのデバイスに送信するには、次に示すようにデバイスの登録トークンを渡します。登録トークンの詳細については、プラットフォームのクライアント設定情報をご覧ください。
Node.js
// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';
const message = {
data: {
score: '850',
time: '2:45'
},
token: registrationToken
};
// Send a message to the device corresponding to the provided
// registration token.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// This registration token comes from the client FCM SDKs.
String registrationToken = "YOUR_REGISTRATION_TOKEN";
// See documentation on defining a message payload.
Message message = Message.builder()
.putData("score", "850")
.putData("time", "2:45")
.setToken(registrationToken)
.build();
// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# This registration token comes from the client FCM SDKs.
registration_token = 'YOUR_REGISTRATION_TOKEN'
# See documentation on defining a message payload.
message = messaging.Message(
data={
'score': '850',
'time': '2:45',
},
token=registration_token,
)
# Send a message to the device corresponding to the provided
# registration token.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// 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);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
cURL コマンド:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"notification":{
"title":"FCM Message",
"body":"This is an FCM Message"
},
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
成功すると、各 send メソッドはメッセージ ID を返します。Firebase Admin SDK は、projects/{project_id}/messages/{message_id}
という形式で ID 文字列を返します。HTTP プロトコル レスポンスは単一の JSON キーです。
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
複数のデバイスにメッセージを送信する
Admin FCM API を使用すると、デバイス登録トークンのリストにメッセージをマルチキャストできます。呼び出しごとに最大 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");
Python
# Create a list containing up to 500 registration tokens.
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Go
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
戻り値は、入力トークンの順序に対応するトークンのリストです。これは、エラーになったトークンを確認するときに便利です。
Node.js
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
'YOUR_REGISTRATION_TOKEN_1',
// …
'YOUR_REGISTRATION_TOKEN_N',
];
const message = {
data: {score: '850', time: '2:45'},
tokens: registrationTokens,
};
getMessaging().sendMulticast(message)
.then((response) => {
if (response.failureCount > 0) {
const failedTokens = [];
response.responses.forEach((resp, idx) => {
if (!resp.success) {
failedTokens.push(registrationTokens[idx]);
}
});
console.log('List of tokens that caused failures: ' + failedTokens);
}
});
Java
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n"
);
MulticastMessage message = MulticastMessage.builder()
.putData("score", "850")
.putData("time", "2:45")
.addAllTokens(registrationTokens)
.build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
List<SendResponse> responses = response.getResponses();
List<String> failedTokens = new ArrayList<>();
for (int i = 0; i < responses.size(); i++) {
if (!responses.get(i).isSuccessful()) {
// The order of responses corresponds to the order of the registration tokens.
failedTokens.add(registrationTokens.get(i));
}
}
System.out.println("List of tokens that caused failures: " + failedTokens);
}
Python
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
'YOUR_REGISTRATION_TOKEN_1',
# ...
'YOUR_REGISTRATION_TOKEN_N',
]
message = messaging.MulticastMessage(
data={'score': '850', 'time': '2:45'},
tokens=registration_tokens,
)
response = messaging.send_multicast(message)
if response.failure_count > 0:
responses = response.responses
failed_tokens = []
for idx, resp in enumerate(responses):
if not resp.success:
# The order of responses corresponds to the order of the registration tokens.
failed_tokens.append(registration_tokens[idx])
print('List of tokens that caused failures: {0}'.format(failed_tokens))
Go
// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Tokens: registrationTokens,
}
br, err := client.SendMulticast(context.Background(), message)
if err != nil {
log.Fatalln(err)
}
if br.FailureCount > 0 {
var failedTokens []string
for idx, resp := range br.Responses {
if !resp.Success {
// The order of responses corresponds to the order of the registration tokens.
failedTokens = append(failedTokens, registrationTokens[idx])
}
}
fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}
C#
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
"YOUR_REGISTRATION_TOKEN_1",
// ...
"YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
Tokens = registrationTokens,
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
var failedTokens = new List<string>();
for (var i = 0; i < response.Responses.Count; i++)
{
if (!response.Responses[i].IsSuccess)
{
// The order of responses corresponds to the order of the registration tokens.
failedTokens.Add(registrationTokens[i]);
}
}
Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}
トピックにメッセージを送信する
トピックを作成した後、クライアント側でクライアント アプリ インスタンスをトピックにサブスクライブするか、またはサーバー 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);
Python
# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'
# See documentation on defining a message payload.
message = messaging.Message(
data={
'score': '850',
'time': '2:45',
},
topic=topic,
)
# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// 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);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
}
}
}
cURL コマンド:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message": {
"topic" : "foo-bar",
"notification": {
"body": "This is a Firebase Cloud Messaging Topic Message!",
"title": "FCM Message"
}
}
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
複数のトピックにメッセージを送信するには、条件を指定します。条件は、ターゲット トピックを指定するブール式です。たとえば次の条件では、TopicA
に加えて TopicB
と TopicC
のどちらか一方にもサブスクライブされているデバイスにメッセージが送信されます。
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
FCM はまず、かっこ内の条件を評価し、次に左から右に式を評価していきます。上記の式では、いずれか 1 つのトピックのみにサブスクライブしているユーザーにはメッセージは送られません。同様に、TopicA
にサブスクライブしていないユーザーにもメッセージは送られません。メッセージが送られるのは、次の組み合わせにサブスクライブしている場合のみです。
TopicA
とTopicB
TopicA
とTopicC
条件式には最大 5 つのトピックを含めることができます。
条件に基づいてメッセージを送信するには:
Node.js
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';
// See documentation on defining a message payload.
const message = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
condition: condition
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";
// See documentation on defining a message payload.
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.setCondition(condition)
.build();
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"
# See documentation on defining a message payload.
message = messaging.Message(
notification=messaging.Notification(
title='$GOOG up 1.43% on the day',
body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
),
condition=condition,
)
# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// 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);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"condition": "'dogs' in topics || 'cats' in topics",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message",
}
}
}
cURL コマンド:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"notification": {
"title": "FCM Message",
"body": "This is a Firebase Cloud Messaging Topic Message!",
},
"condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
デバイス グループにメッセージを送信する
デバイス グループにメッセージを送信するには、HTTP v1 API を使用します。現在、以前のプロトコルに基づいて、HTTP または XMPP、または Node.js 用の Firebase Admin SDK の古いバージョンのいずれかで、非推奨の以前の送信 API を使用してデバイス グループに送信している場合、できるだけ早く HTTP v1 API に移行することを強くおすすめします。以前の送信 API は、2024 年 6 月に無効になり、削除されます。
デバイス グループへのメッセージの送信は個々のデバイスへのメッセージの送信とよく似ており、送信リクエストを承認する方法と同じ方法を使用します。token
フィールドをグループ通知キーに設定します。
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
}
}
}
cURL コマンド
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"data":{
"hello": "This is a Firebase Cloud Messaging device group message!"
},
"token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
メッセージを一括送信する
Admin SDK は、メッセージの一括送信に対応しています。最大 500 件までのメッセージを 1 つのバッチにまとめて 1 回の 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");
Python
# Create a list containing up to 500 messages.
messages = [
messaging.Message(
notification=messaging.Notification('Price drop', '5% off all electronics'),
token=registration_token,
),
# ...
messaging.Message(
notification=messaging.Notification('Price drop', '2% off all books'),
topic='readers-club',
),
]
response = messaging.send_all(messages)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
Go
// Create a list containing up to 500 messages.
messages := []*messaging.Message{
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "5% off all electronics",
},
Token: registrationToken,
},
{
Notification: &messaging.Notification{
Title: "Price drop",
Body: "2% off all books",
},
Topic: "readers-club",
},
}
br, err := client.SendAll(context.Background(), messages)
if err != nil {
log.Fatalln(err)
}
// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
C#
// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "5% off all electronics",
},
Token = registrationToken,
},
new Message()
{
Notification = new Notification()
{
Title = "Price drop",
Body = "2% off all books",
},
Topic = "readers-club",
},
};
var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
ダイレクト ブート対応のメッセージを送信する(Android のみ)
HTTP v1 または以前の HTTP API を使用して、ダイレクト ブート モードでデバイスにメッセージを送信できます。ダイレクト ブート モードでデバイスに送信する前に、クライアント デバイスがダイレクト ブート モードで FCM メッセージを受信できるようにするための手順を完了してください。
FCM v1 HTTP API を使用して送信する
メッセージ リクエストには、リクエスト本文の AndroidConfig
オプションにキー "direct_boot_ok" : true
を含める必要があります。次に例を示します。
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 と FCM v1 HTTP プロトコルは、いずれも message
オブジェクト内のすべてのフィールドをメッセージ リクエストで設定できるようになっています。以下に例を示します。
- メッセージを受け取るすべてのアプリ インスタンスによって解釈される共通のフィールド セット。
AndroidConfig
やWebpushConfig
など、プラットフォーム固有のフィールド セット。指定されたプラットフォームで実行されているアプリ インスタンスによってのみ解釈されます。
プラットフォーム固有のブロックを使用すると、受信時に各種プラットフォームで正しく処理されるように、メッセージを柔軟にカスタマイズできます。FCM バックエンドにより、指定されたすべてのパラメータに従って、メッセージがプラットフォームごとにカスタマイズされます。
共通フィールドを使用する場合
次の場合は共通フィールドを使用します。
- Apple、Android、ウェブのすべてのプラットフォームのアプリ インスタンスをターゲットにする
- トピックにメッセージを送信する
プラットフォームに関係なく、すべてのアプリ インスタンスは次の共通フィールドを解釈できます。
プラットフォーム固有のフィールドを使用する場合
次の場合はプラットフォーム固有のフィールドを使用します。
- 特定のプラットフォームにのみフィールドを送信する
- 共通フィールドに加えてプラットフォーム固有のフィールドを送信する
特定のプラットフォームだけに値を送信する場合は、共通フィールドを使用せずにプラットフォーム固有のフィールドを使用してください。たとえば、Android を除いて Apple プラットフォームとウェブのみに通知を送信するには、2 つの異なるフィールド セット(Apple 用とウェブ用に 1 つずつ)を使用する必要があります。
特定の配信オプションを持つメッセージを送信する場合は、プラットフォーム固有のフィールドを使用してそれらのオプションを設定します。必要に応じてプラットフォームごとに異なる値を指定できます。ただし、すべてのプラットフォームで基本的に同じ値を設定する場合でも、プラットフォーム固有のフィールドを使用する必要があります。これは、プラットフォームごとに値の解釈が多少異なる可能性があるためです。たとえば、Android では秒単位で設定される有効期限が、Apple では有効期日として設定されます。
例: 色とアイコンのオプションを使用した通知メッセージ
次の送信リクエストの例は、すべてのプラットフォームに共通の通知タイトルとコンテンツを送信しますが、Android デバイスにはプラットフォーム固有のオーバーライドも送信します。
Android の場合、このリクエストによって、Android デバイスに表示する特別なアイコンと色が設定されます。AndroidNotification のリファレンスにあるように、色は #rrggbb 形式で指定します。画像は Android アプリのローカル ドローアブル アイコン リソースである必要があります。
ユーザーのデバイスの視覚効果はおおよそ次のようになります。
Node.js
const topicName = 'industry-tech';
const message = {
notification: {
title: '`$FooCorp` up 1.43% on the day',
body: 'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
android: {
notification: {
icon: 'stock_ticker_update',
color: '#7e55c3'
}
},
topic: topicName,
};
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.setAndroidConfig(AndroidConfig.builder()
.setTtl(3600 * 1000)
.setNotification(AndroidNotification.builder()
.setIcon("stock_ticker_update")
.setColor("#f45342")
.build())
.build())
.setApnsConfig(ApnsConfig.builder()
.setAps(Aps.builder()
.setBadge(42)
.build())
.build())
.setTopic("industry-tech")
.build();
Python
message = messaging.Message(
notification=messaging.Notification(
title='$GOOG up 1.43% on the day',
body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
),
android=messaging.AndroidConfig(
ttl=datetime.timedelta(seconds=3600),
priority='normal',
notification=messaging.AndroidNotification(
icon='stock_ticker_update',
color='#f45342'
),
),
apns=messaging.APNSConfig(
payload=messaging.APNSPayload(
aps=messaging.Aps(badge=42),
),
),
topic='industry-tech',
)
Go
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",
};
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic":"industry-tech",
"notification":{
"title":"`$FooCorp` up 1.43% on the day",
"body":"FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
},
"android":{
"notification":{
"icon":"stock_ticker_update",
"color":"#7e55c3"
}
}
}
}
メッセージ本文のプラットフォーム固有のブロックで使用できるキーの詳細については、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);
});
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"
}
}
}
}
メッセージ本文のプラットフォーム固有のブロックで使用できるキーの詳細については、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);
});
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"
}
}
}
}
メッセージ本文のプラットフォーム固有のブロックで使用できるキーの詳細については、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);
});
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"],
},
},
},
},
},
}'
メッセージ本文のプラットフォーム固有のブロックで使用できるキーの詳細については、HTTP v1 のリファレンス ドキュメントをご覧ください。
HTTP v1 API の REST エラーコード
HTTP v1 API の HTTP エラーレスポンスには、エラーコード、エラー メッセージ、エラー ステータスが含まれます。また、エラーの詳細を含む details
配列が含まれることもあります。
エラー レスポンスの例を 2 つ示します。
例 1: データ メッセージに無効な値が含まれている HTTP v1 API リクエストからのエラー レスポンス
{
"error": {
"code": 400,
"message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "message.data[0].value",
"description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
}
]
}
]
}
}
例 2: 無効な登録トークンを含む HTTP v1 API リクエストからのエラー レスポンス
{
"error": {
"code": 400,
"message": "The registration token is not a valid FCM registration token",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
"errorCode": "INVALID_ARGUMENT"
}
]
}
}
どちらのメッセージもコードとステータスは同じですが、details 配列に異なるタイプの値が含まれています。最初の例のタイプは type.googleapis.com/google.rpc.BadRequest
で、リクエスト値のエラーを示します。タイプ type.googleapis.com/google.firebase.fcm.v1.FcmError
の 2 つ目の例には、FCM 固有のエラーがあります。多くのエラーの場合、details 配列には、デバッグして解決策を見つけるために必要な情報が含まれています。
次の表に、FCM v1 REST API のエラーコードとその説明を示しています。
エラーコード | 説明と解決手順 |
---|---|
UNSPECIFIED_ERROR このエラーに関する詳細情報は提供できません。 |
なし |
INVALID_ARGUMENT (HTTP エラーコード = 400)リクエスト パラメータが無効です。無効なフィールドを指定するために、google.rpc.BadRequest タイプの拡張機能が返されます。 |
考えられる原因としては、無効な登録、無効なパッケージ名、メッセージが大きすぎる、無効なデータキー、無効な TTL、その他の無効なパラメータなどがあります。 登録が無効です: サーバーに渡す登録トークンの形式を確認します。登録トークンが、FCM への登録時にクライアント アプリが受信した登録トークンと一致していることを確認します。トークンを切り捨てたり、追加の文字を追加したりしないでください。 パッケージ名が無効です: メッセージの宛先が、リクエストで渡された値と一致するパッケージ名を持つ登録トークンに指定されていることを確認します。 メッセージが大きすぎる: メッセージに含まれているペイロード データの合計サイズが FCM の上限を超えていないことを確認します。上限サイズは、ほとんどのメッセージでは 4,096 バイト、トピック メッセージの場合は 2,048 バイトです。これには、キーと値の両方が含まれます。 データキーが無効: ペイロード データに、FCM 内部で使用されるキー(from、gcm、google という接頭辞が付いた値など)が含まれていないことを確認します。一部の語(collapse_key など)は FCM でも使用されますが、ペイロードでも使用できます。この場合、ペイロードの値は FCM の値で上書きされます。 TTL が無効です: ttl で使用される値が、0~2,419,200(4 週間)の期間(秒単位)を示す整数であることを確認します。 無効なパラメータ: 指定されたパラメータの名前と型が正しいことを確認します。 |
UNREGISTERED (HTTP エラーコード = 404)アプリ インスタンスが FCM から登録解除されました。通常、これは使用しているトークンが有効でなくなったことを意味し、新しいトークンを使用する必要があります。 |
このエラーは、登録トークンがないか、登録されていないトークンが原因で発生することがあります。 登録がない: メッセージのターゲットが token 値の場合は、リクエストに登録トークンが含まれていることを確認します。未登録: 次のようないくつかの状況では、既存の登録トークンが有効でなくなることがあります。 - クライアント アプリが FCM から登録解除した場合。 クライアント アプリが自動的に登録解除された場合。これはユーザーがアプリケーションをアンインストールしたときに発生する可能性があります。たとえば iOS で、APNs フィードバック サービスによって APNs トークンが無効であると報告された場合です。 登録トークンが期限切れになった場合(たとえば、Google が登録トークンを更新する場合、iOS デバイスの APNs トークンが期限切れになった場合)。 クライアント アプリが更新されたが、新しいバージョンはメッセージを受信するように構成されていない場合。 上記のすべての状況で、アプリサーバーから既存の登録トークンを削除し、これを使用したメッセージの送信を停止してください。 |
SENDER_ID_MISMATCH (HTTP エラーコード = 403)認証された送信者 ID が登録トークンの送信者 ID と異なります。 |
登録トークンは、特定の送信者グループに結び付けられています。クライアント アプリを FCM に登録するときに、メッセージの送信が許可される送信者を指定する必要があります。メッセージをクライアント アプリに送信する場合は、これらの送信者 ID のいずれかを使用してください。別の送信者に切り替えると、既存の登録トークンは機能しなくなります。 |
QUOTA_EXCEEDED (HTTP エラーコード = 429)メッセージの宛先の送信上限を超えました。どの割り当てが超過されたかを指定する google.rpc.QuotaFailure タイプの拡張機能が返されます。 |
このエラーは、メッセージ レートに基づく割り当ての超過、デバイス メッセージ レートに基づく割り当ての超過、トピック メッセージ レートに基づく割り当ての超過が原因で発生することがあります。 メッセージ レートの超過: メッセージの送信レートが高すぎます。メッセージの送信レート全体を減らす必要があります。拒否されたメッセージを再試行するには、最初の遅延を 1 分以上に設定した指数バックオフを使用します。 デバイス メッセージ レートの超過: 特定のデバイスへのメッセージ レートが高すぎます。デバイス 1 台に対するメッセージ レートの上限をご覧ください。このデバイスに送信されるメッセージの数を減らし、指数バックオフを使用して送信を再試行します。 トピック メッセージ レートの超過: 特定のトピックのサブスクライバーに対するメッセージ レートが高すぎます。このトピックに送信されるメッセージの数を減らし、最小初期遅延が 1 分間の指数バックオフを使用して送信を再試行します。 |
UNAVAILABLE (HTTP エラーコード = 503)サーバーが過負荷状態です。 |
サーバーで時間内にリクエストを処理できませんでした。同じリクエストを再試行してください。ただし、次の条件を満たす必要があります。 - FCM 接続サーバーからのレスポンスに Retry-After ヘッダーが含まれている場合は、それに従います。 再試行メカニズムに指数バックオフを実装します。(例: 最初に再試行する前に 1 秒間待機した場合は、次の再試行までに少なくとも 2 秒間待機し、さらに次は 4 秒間待機します。)複数のメッセージを送信する場合は、ジッターを適用することを検討してください。詳細については、再試行の処理をご覧ください。問題を引き起こす送信者はブラックリストに登録されるおそれがあります。 |
INTERNAL (HTTP エラーコード = 500)不明な内部エラーが発生しました。 |
リクエストを処理しようとしてサーバーでエラーが発生しました。再試行の処理の推奨事項に沿って、同じリクエストを再試行できます。エラーが解消されない場合は、Firebase サポートまでお問い合わせください。 |
THIRD_PARTY_AUTH_ERROR (HTTP エラーコード = 401)APN 証明書またはウェブプッシュ認証キーが無効であるか、存在しない。 |
iOS デバイスまたはウェブプッシュ登録を対象とするメッセージを送信できませんでした。開発環境用と本番環境用の証明書の有効性を確認します。 |
管理エラーコード
次の表に、Firebase Admin FCM API のエラーコードとその説明(推奨される解決手順を含む)を示します。
エラーコード | 説明と解決手順 |
---|---|
messaging/invalid-argument |
無効な引数が FCM メソッドに提供されました。追加情報がエラー メッセージに含まれています。 |
messaging/invalid-recipient |
意図されたメッセージ受信者が無効です。追加情報がエラー メッセージに含まれています。 |
messaging/invalid-payload |
無効なメッセージ ペイロード オブジェクトが提供されました。追加情報がエラー メッセージに含まれています。 |
messaging/invalid-data-payload-key |
データ メッセージのペイロードに無効なキーが含まれています。制限されているキーについては、DataMessagePayload のリファレンス ドキュメントをご覧ください。
|
messaging/payload-size-limit-exceeded |
提供されたメッセージ ペイロードが FCM のサイズ上限を超えています。ほとんどのメッセージの上限は 4,096 バイトです。トピックに送信されるメッセージの場合、上限は 2,048 バイトです。総ペイロード サイズにはキーと値の両方が含まれます。 |
messaging/invalid-options |
無効なメッセージ オプション オブジェクトが提供されました。追加情報がエラー メッセージに含まれています。 |
messaging/invalid-registration-token |
無効な登録トークンが提供されました。登録トークンが、FCM への登録時にクライアント アプリが受信した登録トークンと一致していることを確認します。文字の追加や削除は行わないでください。 |
messaging/registration-token-not-registered |
提供された登録トークンは登録されていません。次のようなさまざまな理由で、以前は有効であった登録トークンが登録解除されることがあります。
|
messaging/invalid-package-name |
メッセージの宛先である登録トークンのパッケージ名が、提供された restrictedPackageName オプションと一致していません。
|
messaging/message-rate-exceeded |
特定のターゲットへのメッセージ レートが高すぎます。このデバイスまたはトピックに送信されるメッセージの数を減らし、しばらく時間を空けてからこのターゲットへの送信を再試行します。 |
messaging/device-message-rate-exceeded |
特定のデバイスへのメッセージ レートが高すぎます。このデバイスに送信されるメッセージの数を減らし、しばらく時間を空けてからこのデバイスへの送信を再試行します。 |
messaging/topics-message-rate-exceeded |
特定のトピックのサブスクライバーへのメッセージ レートが高すぎます。このトピックに送信されるメッセージの数を減らし、しばらく時間を空けてからこのトピックへの送信を再試行します。 |
messaging/too-many-topics |
登録トークンがサブスクライブしているトピック数はすでに上限に達しており、これ以上サブスクライブすることはできません。 |
messaging/invalid-apns-credentials |
必要な APNs SSL 証明書がアップロードされていないか、期限切れになっているため、Apple デバイスを対象とするメッセージを送信できませんでした。開発環境用と本番環境用の証明書の有効性を確認します。 |
messaging/mismatched-credential |
この SDK の認証に使用された認証情報に、提供された登録トークンに対応するデバイスにメッセージを送信する権限がありません。認証情報と登録トークンが両方とも同じ Firebase プロジェクトに属していることを確認します。Firebase Admin SDK の認証方法については、アプリに Firebase を追加するをご覧ください。 |
messaging/authentication-error |
SDK が FCM サーバーに認証されませんでした。FCM メッセージを送信するための適切な権限を持った認証情報を使用して Firebase Admin SDK を認証していることを確認します。Firebase Admin SDK の認証方法については、アプリに Firebase を追加するをご覧ください。 |
messaging/server-unavailable |
FCM サーバーがリクエストを時間内に処理できませんでした。同じリクエストを再試行しますが、次のことに注意してください。
|
messaging/internal-error |
リクエストを処理しようとして FCM サーバーでエラーが発生しました。上記の messaging/server-unavailable の項目に記載されている要件に従って同じリクエストを再試行できます。エラーが解決しない場合は、バグレポートに問題を報告してください。
|
messaging/unknown-error |
不明なサーバーエラーが返されました。詳細については、エラー メッセージに含まれる生のサーバー レスポンスをご覧ください。このエラーが発生した場合は、完全なエラー メッセージをバグレポートに報告してください。 |
以前のアプリサーバーのプロトコルを使用してメッセージを送信する
現在、以前のプロトコルを使用している場合は、このセクションの手順に従ってメッセージ リクエストを作成します。HTTP で複数のプラットフォームに送信する場合は、v1 プロトコルによってメッセージ リクエストが簡素化されることがありますので注意してください。
特定のデバイスにメッセージを送信する
特定のデバイスにメッセージを送信するには、to
キーを特定のアプリ インスタンスの登録トークンに設定します。登録トークンの詳細については、プラットフォームのクライアント設定情報をご覧ください。
HTTP POST リクエスト
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
HTTP レスポンス
{ "multicast_id": 108, "success": 1, "failure": 0, "results": [ { "message_id": "1:08" } ] }
XMPP メッセージ
<message id="">
<gcm xmlns="google:mobile:data">
{ "data": {
"score": "5x1",
"time": "15:10"
},
"to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}
</gcm>
</message>
XMPP レスポンス
<message id=""> <gcm xmlns="google:mobile:data"> { "from":"REGID", "message_id":"m-1366082849205" "message_type":"ack" } </gcm> </message>
XMPP 接続サーバーには、他にもレスポンス用のオプションがあります。サーバー レスポンスの形式を参照してください。
ダウンストリーム メッセージをクライアント アプリに送信するときに利用可能なメッセージ オプションの一覧については、選択した接続サーバー プロトコル(HTTP または XMPP)のリファレンス情報をご覧ください。
トピックにメッセージを送信する
Firebase Cloud Messaging トピックにメッセージを送信する方法は、個々のデバイスやユーザー グループ宛てのメッセージを送信する場合とよく似ています。アプリサーバーは to
キーに /topics/yourTopic
などの値を設定します。デベロッパーは、正規表現 "/topics/[a-zA-Z0-9-_.~%]+"
に一致するすべてのトピック名を選択できます。
複数のトピックの組み合わせに送信する場合、アプリサーバーは(to
キーではなく)condition
キーで、対象のトピックを指定するブール条件を設定する必要があります。たとえば、TopicA
と、TopicB
または TopicC
のいずれかに登録されたデバイスにメッセージを送信する場合には、次のようになります。
'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
FCM はまず、かっこ内の条件を評価し、次に左から右に式を評価していきます。上記の式では、いずれか 1 つのトピックにサブスクライブしたユーザーにはメッセージは送られません。同様に、TopicA にサブスクライブしていないユーザーにもメッセージは送られません。メッセージが送られるのは、次の組み合わせにサブスクライブしている場合のみです。
- TopicA と TopicB
- TopicA と TopicC
条件式には最大 5 つのトピックを含めることができ、かっこを使用できます。サポートされる演算子: &&
、||
。
トピック HTTP POST リクエスト
単一のトピックに送信します。
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
「犬」(「dogs」)または「猫」(「cats」)のトピックにサブスクライブされたデバイスに送信します。
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>
「犬」(「dogs」)または「猫」(「cats」)のトピックにサブスクライブされたデバイスに送信します。
<message id=""> <gcm xmlns="google:mobile:data"> </gcm> </message>
トピック XMPP レスポンス
// Success example: { "message_id": "1023456" } // failure example: { "error": "TopicsMessageRateExceeded" }
FCM サーバーがトピック送信リクエストに成功または失敗のレスポンスを返すまでに、最大 30 秒の遅延が発生する可能性があります。それに応じて、リクエスト内でアプリサーバーのタイムアウト値を必ず設定してください。
デバイス グループにメッセージを送信する
非推奨のレガシー API を使用してデバイス グループにメッセージを送信する方法は、個々のデバイスへメッセージを送信する方法とよく似ています。この場合、to
パラメータをデバイス グループの一意の通知キーに設定します。
このセクションの例では、以前の HTTP プロトコルと XMPP プロトコルでデバイス グループにデータ メッセージを送信する方法を示しています。
デバイス グループの HTTP POST リクエスト
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA { "to": "aUniqueKey", "data": { "hello": "This is a Firebase Cloud Messaging Device Group Message!", } }
デバイス グループの HTTP レスポンス
以下は「成功」の例です。notification_key
には 2 つの登録トークンが関連付けられており、メッセージは両方のトークンに正しく送信されました。
{ "success": 2, "failure": 0 }
以下は「一部成功」の例です。notification_key
には 3 つの登録トークンが関連付けられています。メッセージは、そのうち 1 つの登録トークンだけに正しく送信されました。レスポンス メッセージには、メッセージを受信できなかった登録トークン(registration_ids
)がリストされます。
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
notification_key
に関連付けられた 1 つ以上の登録トークンにメッセージを配信できない場合、アプリサーバーはバックオフを行いながら再試行を繰り返します。
メンバーのないデバイス グループにサーバーがメッセージを送信しようとすると、レスポンスには次のように成功 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 つの登録トークンが関連付けられています。メッセージは、そのうち 1 つの登録トークンだけに正しく送信されました。レスポンス メッセージには、メッセージを受信できなかった登録トークンがリストされます。
{ "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 Server 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()
メソッドは、FCM からのレスポンスを含む MessagingDevicesResponse
オブジェクトで解決される Promise を返します。戻り値の型の形式は、単一の登録トークンと登録トークンの配列のどちらを渡したときも同じです。
認証エラーやレート制限などのいくつかのケースで、メッセージ全体の処理が失敗する場合があります。このような場合、sendToDevice()
によって返される Promise はエラーで拒否されます。すべてのエラーコード、その説明、解決手順を記載した一覧については、Admin FCM API のエラーをご覧ください。
デバイス グループに送信する
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()
メソッドは、FCM からのレスポンスを含む MessagingDevicesResponse
オブジェクトで解決される Promise を返します。
認証エラーやレート制限などのいくつかのケースで、メッセージ全体の処理が失敗する場合があります。このような場合、sendToDeviceGroup()
によって返される Promise はエラーで拒否されます。すべてのエラーコード、その説明、解決手順を記載した一覧については、Admin FCM API のエラーをご覧ください。
メッセージ ペイロードの定義
以前の FCM プロトコルに基づく上記のメソッドは、2 番目の引数としてメッセージ ペイロードを受け入れ、通知メッセージとデータ メッセージの両方をサポートします。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
のリファレンス ドキュメントをご覧ください。
データ メッセージのペイロードはカスタムの Key-Value ペアで構成されており、すべての値が文字列でなければならないなど、いくつかの制限があります。制限の一覧については、DataMessagePayload
のリファレンス ドキュメントをご覧ください。
メッセージ オプションの定義
以前の FCM プロトコルに基づく上記のメソッドには、メッセージのオプションを指定する 3 番目の引数を任意に指定できます。たとえば次の例は、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
のリファレンス ドキュメントをご覧ください。