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

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

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

デバイス グループの管理

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

  1. グループに追加するデバイスそれぞれについて、登録トークンを取得します。

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