ウェブ / JavaScript でトピックにメッセージを送信する

パブリッシュ / サブスクライブ モデルに基づく FCM トピック メッセージングでは、特定のトピックにオプトインした複数のデバイスにメッセージを送信できます。必要に応じて作成したトピック メッセージを FCM がルーティング処理し、確実に正しいデバイスにメッセージを配信します。

たとえば、地域の潮汐予測アプリのユーザーは、「潮流警報」トピックにオプトインし、特定の地域の海釣りに最適な状況の通知を受信できます。スポーツアプリのユーザーは、お気に入りのチームの実況ゲームスコアの自動更新に登録できます。

トピックに関する留意点を以下に示します。

  • トピック メッセージングは、天気、その他の広く入手可能な情報コンテンツに最適です。
  • トピック メッセージは、レイテンシではなくスループットに対して最適化されます。単一のデバイスまたはデバイスの小グループに高速で安全に配信する場合は、トピックではなく登録トークンをメッセージのターゲットとしてください
  • 各ユーザーの複数のデバイスにメッセージを送信する必要がある場合は、そのようなユースケース向けのデバイス グループ メッセージングを検討してください。
  • トピック メッセージングでは、トピックごとの登録数に制限はありませんが、FCM により次の制限が課されます。
    • 1 つのアプリ インスタンスを登録できるのは、2,000 トピックまでです。
    • 一括インポートを使用してアプリ インスタンスを登録する場合、各リクエストのアプリ インスタンスの数が 1,000 に制限されます。
    • 新規登録の頻度がプロジェクトごとに制限されます。短期間に多数の登録リクエストを送信すると、FCM サーバーから 429 RESOURCE_EXHAUSTED(「割り当てを超過した」)というレスポンスが返されます。この場合は、指数バックオフを使用して再試行します。

クライアント アプリをトピックに登録する

登録トークンとトピック名がわかっていれば、Google Instance ID サーバー API を使用して、トピックにトークンを追加できます。このエンドポイントで Instance ID API を呼び出して、アプリ インスタンスの登録トークンとトピック名を指定します。

 https://iid.googleapis.com/iid/v1/<REGISTRATION_TOKEN>/rel/topics/<TOPIC_NAME>

たとえば、「movies」という名前のトピックにアプリ インスタンスを登録するには、次に示すように、認証ヘッダーにサーバー API キーを追加して POST リクエストをサーバーからエンドポイントに送信します。

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

サーバーキーの機密性を維持するため、このタイプのリクエストをクライアントから送信しないでください。

リクエストが成功した場合は、HTTP 200 OK が返されます。エラー レスポンスの詳細と一括リクエストの送信方法については、アプリ インスタンス用の関係マップの作成をご覧ください。

メッセージを受信して処理する

FCM は、他のダウンストリーム メッセージと同じようにトピック メッセージを配信します。クライアントでメッセージを処理する方法は、ウェブページの状態(フォアグラウンドかバックグラウンドか)や、このセクションで説明する要因によって異なります。

メッセージの動作は、ページがフォアグラウンドにある(フォーカスされている)か、ページがバックグラウンドにあり、他のタブに隠されているか、完全に閉じられているかによって異なります。いずれの場合も、onMessage コールバックをページで処理する必要がありますが、バックグラウンドの場合はこれに加えて setBackgroundMessageHandler を処理するか、ユーザーがウェブアプリをフォアグラウンドに戻せるように表示通知を構成する必要があります。

アプリの状態 通知 データ ペイロード 両方
フォアグラウンド onMessage onMessage onMessage
バックグラウンド(Service Worker) SDK によって表示される通知 setBackgroundMessageHandler SDK によって表示される通知

ウェブアプリがフォアグラウンドの場合にメッセージを処理する

アプリが onMessage イベントを受信するには、firebase-messaging-sw.js で Firebase メッセージング Service Worker を定義する必要があります。あるいは、useServiceWorker を使って既存の Service Worker を指定できます。

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

アプリがフォアグラウンドにある(ユーザーがウェブアプリを現在閲覧している)場合は、そのページでデータと通知ペイロードを直接受信できます。

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.setBackgroundMessageHandler` handler.
messaging.onMessage(function(payload) {
  console.log('Message received. ', payload);
  // ...
});

ウェブアプリがバックグラウンドの場合にメッセージを処理する

アプリがバックグラウンドで動作中になんらかのメッセージを受信すると、ブラウザ内の表示通知がトリガーされます。この通知に関するオプション(タイトルやクリック アクションなど)は、アプリサーバーからの送信リクエスト、またはクライアント上の Service Worker ロジックで指定できます。

送信リクエストでの通知オプションの設定

アプリサーバーから送信される通知メッセージの場合は、FCM JavaScript API が click_action キーをサポートします。通常、これはウェブアプリ内のページに設定されます。

https://fcm.googleapis.com//v1/projects/<YOUR-PROJECT-ID>/messages:send
Content-Type: application/json
Authorization: bearer <YOUR-ACCESS-TOKEN>

{
  "message": {
    "topic": "matchday"
    "notification": {
      "title": "Background Message Title",
      "body": "Background message body"
    },
    "webpush": {
      "fcm_options": {
        "link": "https://dummypage.com"
      }
    }
  }
}

クリック アクションが指しているページがすでにブラウザタブで開いている場合は、通知をクリックするとそのタブがフォアグラウンドに移動します。そのページがまだ開いていない場合は、通知をクリックするとそのページが新しいタブで開きます。

データ メッセージは click_action をサポートしないため、すべてのデータ メッセージに通知ペイロードを追加することをおすすめします。または、Service Worker を使用して通知を処理することもできます。

通知メッセージとデータ メッセージの違いの説明については、メッセージのタイプをご覧ください。

Service Worker での通知オプションの設定

通知メッセージとデータ メッセージの両方に関して、Service Worker で通知オプションを設定できます。まず、Service Worker でアプリを初期化します。

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

オプションを設定するには、firebase-messaging-sw.jssetBackgroundMessageHandler を呼び出します。この例では、タイトル、本文、アイコン、クリック アクション用のオプションを設定します。

messaging.setBackgroundMessageHandler(function(payload) {
  console.log('[firebase-messaging-sw.js] Received background message ', payload);
  // Customize notification here
  var notificationTitle = 'Background Message Title';
  var notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  return self.registration.showNotification(notificationTitle,
    notificationOptions);
});

ビルド送信リクエスト

サーバー側から Firebase Cloud Messaging トピックへのメッセージの送信する方法は、個々のデバイスやユーザー グループ宛てのメッセージを送信する場合とよく似ています。アプリサーバーは to キーに /topics/yourTopic などの値を設定します。デベロッパーは、正規表現 "/topics/[a-zA-Z0-9-_.~%]+" に一致するすべてのトピック名を選択できます。

トピック HTTP POST リクエスト

単一のトピックに送信します。

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "to" : "/topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}

トピック HTTP レスポンス

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

トピック XMPP メッセージ

単一のトピックに送信します。

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "to" : "/topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}
  </gcm>
</message>

トピック XMPP レスポンス

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

次のステップ

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

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