コンソールへ移動

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

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

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

デバイス グループの管理

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

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

  2. notification_key を作成します。これは、特定のグループ(通常はユーザー)とそのグループに関連付けられたすべての登録トークンをマッピングさせることで、デバイス グループを識別します。通知キーは、アプリサーバー上でも Android クライアント アプリ上でも作成できます。

デバイス グループの基本管理(グループの作成と削除、デバイスの追加や削除)は通常、アプリサーバーを介して行われます。サポートされているキーの一覧については、以前の HTTP プロトコルのリファレンスをご覧ください。

あるいは、Android クライアント アプリでクライアント側からデバイス グループを管理することもできます。

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

デバイス グループの作成

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

HTTP POST リクエスト

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

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
Authorization:key=API_KEY
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["4", "8", "15", "16", "23", "42"]
}

notification_key_name は、指定されたグループを一意に表す名前または識別子(たとえばユーザー名)です。notification_key_namenotification_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
Authorization:key=API_KEY
project_id:SENDER_ID
{}

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

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

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

HTTP POST リクエスト

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

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

レスポンスの形式

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

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

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

デバイス グループへメッセージを送信する方法は、個々のデバイスへメッセージを送信する場合とよく似ています。この場合、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)のリファレンス情報をご覧ください。