アプリサーバーからの送信リクエストを作成する

Firebase Admin SDK や FCM アプリサーバー プロトコルを使用して、メッセージ リクエストを作成し、それらを次のタイプのターゲットに送信できます。

  • トピックの名前
  • 条件
  • デバイス登録トークン
  • デバイス グループの名前(以前のプロトコルおよび Node.js 用の Firebase Admin SDK のみ)

事前定義フィールドで構成される通知ペイロード、独自のユーザー定義フィールドのデータ ペイロード、またはそれら両方のタイプのペイロードを含むメッセージを使用して、メッセージを送信できます。詳細については、メッセージのタイプを参照してください。

このページの例では、Firebase Admin SDK(NodeJavaPythonC#Go をサポート)と v1 HTTP プロトコルを使用して通知メッセージを送信する方法を示しています。また、以前の HTTP および XMPP プロトコルによりメッセージを送信するためのガイダンスもあります。

特定のデバイスにメッセージを送信する

特定の 1 つのデバイスに送信するには、次に示すようにデバイスの登録トークンを渡します。登録トークンの詳細については、プラットフォームのクライアント設定情報をご覧ください。

Node.js

// This registration token comes from the client FCM SDKs.
var registrationToken = 'YOUR_REGISTRATION_TOKEN';

var message = {
  data: {
    score: '850',
    time: '2:45'
  },
  token: registrationToken
};

// Send a message to the device corresponding to the provided
// registration token.
admin.messaging().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"
    }

トピックにメッセージを送信する

トピックにメッセージを送信するには、送信リクエストで目的のトピック名を指定します。

Node.js

// The topic name can be optionally prefixed with "/topics/".
var topic = 'highScores';

var message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
admin.messaging().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 に加えて TopicBTopicC のどちらか一方にも登録されているデバイスにメッセージを送信します。

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

条件式はまずかっこ内から評価され、次に左から右に評価されます。上記の式では、いずれか 1 つのトピックだけに登録したユーザーにはメッセージは送られません。同様に、TopicA に登録していないユーザーにもメッセージは送られません。メッセージが送られるのは、次の組み合わせに登録している場合のみです。

  • TopicATopicB
  • TopicATopicC

条件式には最大 5 つのトピックを含めることができます。

条件に送信するには:

Node.js

// 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 = {
  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.
admin.messaging().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(new Notification(
        "$GOOG up 1.43% on the day",
        "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."))
    .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

プラットフォーム間でメッセージをカスタマイズする

Firebase Admin SDK と FCM v1 HTTP プロトコルの両方を使用すると、メッセージ リクエストで message オブジェクト内のすべてのフィールドを設定できます。これには以下のフィールドが含まれます。

  • メッセージを受け取るすべてのアプリ インスタンスによって解釈される共通のフィールド セット。
  • AndroidConfigWebpushConfig など、プラットフォーム固有のフィールド セット。指定されたプラットフォームで実行されているアプリ インスタンスによってのみ解釈されます。

プラットフォーム固有のブロックを使用すると、各種プラットフォームで受信時に正しく処理されるようにメッセージを柔軟にカスタマイズできます。FCM バックエンドは、指定されたすべてのパラメータを考慮に入れて、プラットフォームごとにメッセージをカスタマイズします。

共通フィールドを使用する場合

次の場合は共通フィールドを使用します。

  • iOS、Android、ウェブのすべてのプラットフォームでアプリ インスタンスをターゲティングする
  • トピックにメッセージを送信する

プラットフォームに関係なく、すべてのアプリ インスタンスは次の共通フィールドを解釈できます。

プラットフォーム固有のフィールドを使用する場合

次の場合はプラットフォーム固有のフィールドを使用します。

  • 特定のプラットフォームにのみフィールドを送信する
  • 共通フィールドに加えてプラットフォーム固有のフィールドを送信する

特定のプラットフォームだけに値を送信する場合は、共通のフィールドを使用せずにプラットフォーム固有のフィールドを使用してください。たとえば、Android を除いて iOS とウェブのみに通知を送信するには、2 つの異なるフィールド セット(iOS 用とウェブ用に 1 つずつ)を使用する必要があります。

特定の配信オプションを使用してメッセージを送信する場合は、そうしたオプションの設定にプラットフォーム固有のフィールドを使用します。必要に応じてプラットフォームごとに異なる値を指定できます。ただし、プラットフォーム間で基本的に同じ値を設定したい場合でも、プラットフォーム固有のフィールドを使用する必要があります。これは、プラットフォームごとに値の解釈が若干異なる可能性があるためです。たとえば、有効期間は Android では秒単位で設定されますが、iOS では有効期日として設定されます。

例: プラットフォーム固有の配信オプションを使用した通知メッセージ

次の send リクエストは、すべてのプラットフォームに共通の通知タイトルとコンテンツを送信しますが、プラットフォーム固有のオーバーライドも送信します。リクエストの詳細は次のとおりです。

  • Android デバイスに表示する特別なアイコンと色とともに、Android の有効期間を長めに設定します。
  • iOS デバイスに配信するために、APN ペイロードに iOS 専用 badge フィールドを設定します。

Node.js

var message = {
  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: {
    ttl: 3600 * 1000,
    notification: {
      icon: 'stock_ticker_update',
      color: '#f45342',
    },
  },
  apns: {
    payload: {
      aps: {
        badge: 42,
      },
    },
  },
  topic: 'industry-tech'
};

Java

Message message = Message.builder()
    .setNotification(new Notification(
        "$GOOG up 1.43% on the day",
        "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."))
    .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",
}

REST

{
  "message":{
     "topic":"industry-tech",
     "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":{
       "ttl":"3600s",
       "notification"{
         "icon:stock_ticker_update"
         "color:#f45342"
       }
     },
     "apns": {
       "payload": {
         "aps": {
           "badge": "42"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

メッセージ本文のプラットフォーム固有のブロックで使用できるキーの詳細については、HTTP v1 のリファレンス ドキュメントをご覧ください。

Admin FCM SDK エラー リファレンス

次の表に、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 提供された登録トークンは登録されていません。次のようなさまざまな理由で、以前は有効であった登録トークンが登録解除されることがあります。
  • クライアント アプリが FCM から登録解除された。
  • クライアント アプリが自動的に登録解除された。これは、ユーザーがアプリケーションをアンインストールした場合、または iOS で APNs フィードバック サービスによって APNs トークンが無効であると報告された場合に起こる可能性があります。
  • 登録トークンの有効期限が切れた。たとえば、Google が登録トークンの更新を決定したり、iOS 端末の 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 必要な APNs SSL 証明書がアップロードされていないか、期限切れになっているため、iOS 端末を対象とするメッセージを送信できませんでした。開発用証明書と本番用証明書の有効性を確認します。
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 サーバーがリクエストを時間内に処理できませんでした。同じリクエストを再試行しますが、次のことに注意してください。
  • FCM 接続サーバーからのレスポンスに Retry-After ヘッダーが含まれている場合は、それに従います。
  • 再試行メカニズムに指数バックオフを実装します。たとえば、1 秒後に最初の再試行を行った場合は、次の試行まで少なくとも 2 秒待ち、その次の再試行まで少なくとも 4 秒待ちます。複数のメッセージを再送信する場合は、すべてのメッセージの新規リクエストが同時に発行されないように、ランダムな秒数を加えて各メッセージの送信を個別に遅らせます。
問題のある送信者はブラックリストに登録されるおそれがあります。
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 つのトピックを含めることができ、かっこを使用できます。使用できる演算子は &&||! です。! の使用方法に注意してください。

!('TopicA' in topics)

この式では、どのトピックにも登録されていないアプリ インスタンスを含め、TopicA に登録されていないアプリ インスタンスすべてがメッセージを受信します。

アプリサーバーのキーの詳細については、選択した接続サーバー プロトコル(HTTP または XMPP)のリファレンス情報をご覧ください。このページでは、メッセージをトピックに送信する方法として HTTP と XMPP の両方の例を示しています。

トピック 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 秒の遅延が発生する可能性があります。それに応じて、リクエスト内でアプリサーバーのタイムアウト値を必ず設定してください。

メッセージ オプションの一覧については、選択した接続サーバー プロトコル(HTTP または XMPP)のリファレンス情報をご覧ください。

デバイス グループにメッセージを送信する

デバイス グループへメッセージを送信する方法は、個々のデバイスへメッセージを送信する方法とよく似ています。この場合、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 つの登録トークンだけに正しく送信されました。レスポンス メッセージには、メッセージを受信できなかった登録トークンがリストされます。

{
  "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 での以前の send メソッド

Firebase Admin Node.js SDK は、以前の FCM サーバー API に基づいて(FCM)メッセージを送信するためのメソッドをサポートします。これらのメソッドは、send() メソッドとは異なる引数を受け入れます。可能であれば send() メソッドを使用し、このページで説明されているメソッドは、個々のデバイスまたはデバイス グループにメッセージを送信する場合にのみ使用してください。

個々の端末に送信する

登録トークンを sendToDevice() メソッドに渡すと、そのデバイスにメッセージを送信できます。

Node.js

// This registration token comes from the client FCM SDKs.
var registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
var payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device corresponding to the provided
// registration token.
admin.messaging().sendToDevice(registrationToken, payload)
  .then(function(response) {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

また、sendToDevice() メソッドに単一の登録トークンではなく登録トークンの配列を渡すことで、マルチキャスト メッセージ(つまり複数のデバイスを宛先とするメッセージ)も送信できます。

Node.js

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...',
  // ...
  'ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf...'
];

// See the "Defining the message payload" section below for details
// on how to define a message payload.
var payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the devices corresponding to the provided
// registration tokens.
admin.messaging().sendToDevice(registrationTokens, payload)
  .then(function(response) {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

sendToDevice() メソッドは、FCM からのレスポンスを含む MessagingDevicesResponse オブジェクトで解決される Promise を返します。戻り値の型の形式は、単一の登録トークンと登録トークンの配列のどちらを渡したときも同じです。

認証エラーやレート制限などのいくつかのケースでは、メッセージ全体の処理が失敗する場合があります。このような場合、sendToDevice() によって返される Promise はエラーで拒否されます。すべてのエラーコードとその説明、および解決手順を記載した一覧については、Admin FCM API のエラーをご覧ください。

デバイス グループに送信する

デバイス グループ メッセージングを使用すると、1 つのグループに複数のデバイスを追加できます。これはトピック メッセージングに似ていますが、サーバーのみがグループ メンバーシップを管理するための認証が含まれています。たとえば、さまざまなスマートフォン モデルに応じて異なるメッセージを送信する場合、サーバーは適切なグループに対して登録を追加または削除し、適切なメッセージを各グループに送信できます。デバイス グループ メッセージングはトピック メッセージングとは異なり、サーバーからデバイス グループを管理します(アプリケーション内で直接管理するのではありません)。

アプリサーバーでは、以前の XMPP プロトコルや HTTP プロトコルを介してデバイス グループ メッセージングを使用できます。 以前のプロトコルに基づく Node.js 用の Firebase Admin SDK でも、デバイス グループ メッセージング機能を利用できます。1 つの通知キーで送信できるメンバーの最大数は 20 です。

デバイス グループを作成し、アプリサーバーまたは Android クライアントを通じて通知キーを生成できます。詳細については、端末グループの管理をご覧ください。

sendToDeviceGroup() メソッドでデバイス グループの通知キーを指定して、そのデバイス グループにメッセージを送信できます。

Node.js

// See the "Managing device groups" link above on how to generate a
// notification key.
var notificationKey = 'some-notification-key';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
var payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device group corresponding to the provided
// notification key.
admin.messaging().sendToDeviceGroup(notificationKey, payload)
  .then(function(response) {
    // See the MessagingDeviceGroupResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

sendToDeviceGroup() メソッドは、FCM からのレスポンスを含む MessagingDeviceGroupResponse オブジェクトで解決される Promise を返します。

認証エラーやレート制限などのいくつかのケースでは、メッセージ全体の処理が失敗する場合があります。このような場合、sendToDeviceGroup() によって返される Promise はエラーで拒否されます。すべてのエラーコードとその説明、および解決手順を記載した一覧については、Admin FCM API のエラーをご覧ください。

メッセージ ペイロードの定義

以前の FCM プロトコルに基づく上記のメソッドは、2 番目の引数としてメッセージ ペイロードを受け入れ、通知メッセージとデータ メッセージの両方をサポートします。datanotification の一方または両方のキーを含むオブジェクトを作成することで、一方または両方のメッセージ タイプを指定できます。たとえば、それぞれの種類のメッセージ ペイロードを定義する方法は次のとおりです。

通知メッセージ

var payload = {
  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.'
  }
};

データ メッセージ

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

両方のメッセージ

var payload = {
  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.'
  },
  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.
var registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section above for details
// on how to define a message payload.
var 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.
var options = {
  priority: 'high',
  timeToLive: 60 * 60 * 24
};

// Send a message to the device corresponding to the provided
// registration token with the provided options.
admin.messaging().sendToDevice(registrationToken, payload, options)
  .then(function(response) {
    console.log('Successfully sent message:', response);
  })
  .catch(function(error) {
    console.log('Error sending message:', error);
  });

使用可能なオプションの一覧については、MessagingOptions のリファレンス ドキュメントをご覧ください。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。