ウェブ / JavaScript でデバイスグループにメッセージを送信する

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

1 つの通知キーで送信できるメンバーの最大数は 20 です。

デバイスグループの管理

デバイスグループにメッセージを送信する前に、次の手順を行う必要があります。

グループに追加するデバイスそれぞれについて、登録トークンを取得します。
notification_key を作成します。これは、特定のグループ（通常はユーザー）とそのグループに関連付けられたすべての登録トークンをマッピングさせることで、デバイスグループを識別します。通知キーはアプリサーバー上で作成できます。

デバイスグループの基本的な管理（グループの作成と削除、デバイスの追加または削除）は、送信リクエストを認証するために有効期間が短いトークンを使用して、HTTP v1 API を介して行われます。サポートされているキーのリストについては、デバイスグループ管理キーをご覧ください。

アプリサーバーでのデバイスグループの管理

デバイスグループの作成

デバイスグループを作成するには、グループの名前を指定する POST リクエストと、デバイスの登録トークンのリストを送信します。FCM は、デバイスグループを表す新しい notification_key を返します。

HTTP POST リクエスト

次のようなリクエストを https://fcm.googleapis.com/fcm/notification に送信します。

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]

notification_key_name は、指定されたグループを一意に表す名前または識別子（たとえばユーザー名）です。notification_key_name と notification_key は、登録トークンのグループに対して一意になります。同じ送信者 ID のクライアントアプリが複数ある場合は、クライアントアプリごとに notification_key_name が一意であることが重要です。これにより、意図したターゲットアプリだけにメッセージが送信されます。

レスポンスの形式

リクエストが成功すると、次のような notification_key が返されます。

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

今後のオペレーションで使用するために、notification_key と、対応する notification_key_name を保存します。

通知キーの取得

既存の通知キーを取得する必要がある場合は、次のように GET リクエストで notification_key_name を使用します。

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

指定した通知キー名に対する GET リクエストごとに、エンコードされた一意の文字列がサーバーから返されます。各文字列は異なるキーであるかのように見える場合がありますが、実際には有効な「notification_key」値です。

デバイスグループでのデバイスの追加と削除

既存のグループでデバイスを追加または削除するには、operation パラメータを add または remove に設定した POST リクエストを送信し、追加や削除の対象となる登録トークンを指定します。

HTTP POST リクエスト

たとえば、登録トークンが bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1... のデバイスを appUser-Chris に追加するには、次のリクエストを送信します。

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

レスポンスの形式

デバイスの追加または削除のリクエストが成功すると、次のような notification_key が返されます。

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

デバイスグループ管理キー

次の表は、デバイスグループを作成し、メンバーを追加および削除するためのキーを示しています。

表 10.デバイスグループ管理キー

パラメータ	指定方法	説明
`operation`	必須、文字列	実行するオペレーション。有効な値は、`create`、`add`、`remove` です。
`notification_key_name`	必須、文字列	作成または変更するデバイスグループのユーザー定義の名前。
`notification_key`	必須（`create` オペレーション、文字列を除く）	デバイスグループの一意の識別子。この値は、正常な `create` オペレーションのレスポンスで返され、デバイスグループに対する後続のすべてのオペレーションに必要です。
`registration_ids`	必須、文字列の配列	追加または削除するデバイストークン。デバイスグループから既存のすべての登録トークンを削除すると、デバイスグループ自体も削除されます。

デバイスグループへのダウンストリームメッセージの送信

デバイスグループにメッセージを送信するには、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

ウェブ / JavaScript でデバイス グループにメッセージを送信する

デバイス グループの管理

アプリサーバーでのデバイス グループの管理

デバイス グループの作成