このページは Cloud Translation API によって翻訳されました。

FCM トピックを使用した最初のマルチキャストプッシュメッセージ

1. はじめに

目標

この Codelab では、FCM トピックを使用してアプリインスタンスのさまざまなサブグループにプッシュメッセージをマルチキャストできるように、マルチプラットフォームアプリを計測する方法を学びます。

完了すると、FCM インフラストラクチャを利用して、これらのサブグループを管理したり、サブグループにマルチキャストプッシュメッセージを送信したりできるようになります。

トピックの概要

トピックは、FCM インフラストラクチャでサポートされている、アプリインスタンスのサブグループにメッセージを送信する方法です。

FCM には、メッセージを送信し、これらのトピックへの登録を維持するための API が用意されています。アプリインスタンスをトピックに関連付けたり、関連付けを解除したりする操作は、それぞれサブスクライブと登録解除と呼ばれます。

トピックは、一般公開されているコンテンツに使用する必要があります。たとえば、天気予報の更新に関するメッセージなどです。ユーザーの機密情報を含むメッセージを送信する場合は、Firebase Admin SDK を使用して複数のデバイスにメッセージをマルチキャストします。

トピックベースのマルチキャストは、スループット向けに最適化されています。

学習内容

モバイルアプリからユーザーをトピックに登録（および登録解除）する方法。
トピックを使用してマルチキャストプッシュメッセージを送信する方法。
トピック条件を使用して複数のトピックにメッセージを送信する方法。
サーバーサイドでトピックサブスクリプションを管理し、一括で登録と登録解除を行う方法。

作成するアプリの概要

トピックを登録/登録解除し、トピックに送信されたときにメッセージを受信する Android アプリ。
Firebase Admin SDK を使用したサーバーサイド統合。FCM API を介してトピックメッセージを送信するために使用されます。

必要なもの

Chrome などの任意のブラウザ。
Java アプリケーション開発用の IntelliJ IDEA IDE。
- インストール時に Gradle のサポートを有効にしてください。
Android アプリケーションを開発するための Android Studio IDE。
Android アプリケーションを実行するデバイス。次のいずれか:
- Android Emulator（Android Studio でのセットアップが必要）
- パソコンに接続され、デベロッパーモードに設定されている Android デバイスの実機。
Firebase プロジェクトの作成と管理に使用する Google アカウント。

2. 設定方法

コードを取得する

コマンドラインから GitHub リポジトリのクローンを作成します。

git clone https://github.com/firebase/quickstart-android.git fcm-codelab

サンプルコードは fcm-codelab ディレクトリにクローンされます。

cd fcm-codelab

この Codelab のスターターアプリは、fcm-topics-codelab ブランチの messaging ディレクトリにあります。スターターコードにアクセスする手順は次のとおりです。StockNewsApp と StockNewsServer の 2 つのディレクトリが含まれています。前者はスターター Android アプリを含み、後者はスターターサーバーサイドコードを含みます。

git checkout fcm-topics-codelab
cd messaging/fcm-topics-codelab/starter

この Codelab の完成版は messaging/fcm-topics-codelab/completed ディレクトリに配置されています。

Firebase プロジェクトを作成する

Google アカウントを使用して Firebase コンソールにログインします。
ボタンをクリックして新しいプロジェクトを作成し、プロジェクト名（例: StockNews）を入力します。
このプロジェクト名は Firebase インターフェースで表示名として使用され、Firebase はこのプロジェクト名に基づいて一意のプロジェクト ID を自動作成します。必要に応じて、ここで編集アイコンをクリックして、任意のプロジェクト ID を設定できます。ただし、プロジェクトの作成後にこの ID を変更することはできません。

後で Firebase CLI で Firebase プロジェクトを識別するために必要となるため、プロジェクト ID を覚えておいてください。ID を忘れた場合は、後で [プロジェクトの設定] で確認できます。
[続行] をクリックします。
Firebase の利用規約が表示されたら、内容を読み、同意して [続行] をクリックします。
（省略可）Firebase コンソールで AI アシスタンス（「Gemini in Firebase」）を有効にします。
この Codelab では Google アナリティクスは必要ないため、Google アナリティクスのオプションをオフに切り替えます。
[プロジェクトを作成] をクリックし、プロジェクトのプロビジョニングが完了するまで待ってから、[続行] をクリックします。

これで完了です。これで Firebase プロジェクトが作成されました。

3. プラットフォーム固有の Firebase アプリ構成

Firebase サポートを有効にするために必要なコード変更のほとんどは、作業中のプロジェクトにすでにチェックインされています。ただし、モバイルプラットフォームのサポートを追加するには、次のことを行う必要があります。

目的のプラットフォームを Firebase プロジェクトに登録する
プラットフォーム固有の構成ファイルをダウンロードしてコードに追加する。

この Codelab では、Android Firebase アプリを追加します。

Android を構成する

Firebase コンソールの左側のナビゲーションバーの上部にある設定歯車で [プロジェクトの設定] を選択し、[全般] ページの [マイアプリ] の下にある [Android] アイコンをクリックします。

以下のダイアログが表示されます。

指定が必要な重要な値は、Android パッケージ名です。com.ticker.stocknews に設定します。
1. ここで指定するパッケージ名は、スターター StockNewsApp コードの AndroidManifest.xml で指定されているものと同じである必要があります。この設定を確認または変更するには、次の手順に沿って操作します。
  1. StockNewsApp ディレクトリで、ファイル app/src/main/AndroidManifest.xml を開きます。
  2. manifest 要素内にある package 属性の文字列値を確認します。この値は Android パッケージ名です。

Firebase のダイアログで、コピーしたパッケージ名を [Android パッケージ名] フィールドに貼り付けます。
このアプリはリリースされないため、この Codelab では [デバッグ用の署名証明書 SHA-1] の指定は不要です。このフィールドは空白のままにします。
[アプリを登録] をクリックします。
引き続き Firebase コンソールで、指示に沿って構成ファイル google-services.json をダウンロードします。
残りの設定手順はスキップできます。他のすべての設定はスターターアプリのコードですでに構成されています。Firebase コンソールのメインページにアプリが表示されます。
先ほどダウンロードした google-services.json ファイルを messaging/fcm-topics-codelab/starter/StockNewsApp/app ディレクトリにコピーします。

4. アプリをビルドして実行する

アプリで実際に作業を開始する準備が整いました。まず、アプリをビルドして実行します。

スターターアプリをインポートする

Android Studio を起動し、スターターコードディレクトリから messaging/fcm-topics-codelab/starter/StockNewsApp をインポートします。

プロジェクトが読み込まれた後、ローカルで行った変更の一部が Git によりトラッキングされていないことを示すアラートが表示される場合もあります。その場合は、[Ignore] または右上の [X] をクリックします。（変更を Git リポジトリにプッシュバックすることはありません）。

[Android] ビューの場合は、プロジェクトウィンドウの左上に次のような画像が表示されます（[Project] ビューの場合は、プロジェクトを展開すると同じ画像が表示されます）。

初回は、バックグラウンドでプロジェクトをコンパイルするのに数秒かかることがあります。その間、Android Studio の下部にあるステータスバーにスピナーが表示されます。

コンパイルが完了するまで、コードを変更しないことをおすすめします。このコンパイルで、必要なすべてのコンポーネントを Android Studio に取り込むことができます。

また、「Reload for language changes to take effect?」のようなメッセージが表示された場合は、[Yes] を選択します。

エミュレータのセットアップ

Android エミュレータのセットアップについてサポートが必要な場合は、アプリを実行するをご覧ください。

Android アプリのスターターコードについて

スターターコードは、最小限の機能と UI を備えた軽量の Android アプリです。
firebase-messaging SDK への依存関係は、すでに app/build.gradle ファイルに追加されています。

AndroidManifest.xml には、MESSAGING_EVENT コールバックハンドラがすでに追加されています。
- このハンドラ StockNewsMessagingService.java は、さまざまな Firebase Cloud Messaging 関連機能を提供する FirebaseMessagingService クラスを拡張します。詳しくは、FirebaseMessagingService のドキュメントをご覧ください。
- onNewToken 関数は、FCM 登録トークンが作成または更新されたときに呼び出されます。詳細については、トークン生成をモニタリングするをご覧ください。
- メッセージを受信し、アプリがフォアグラウンドにある場合、onMessageReceived 関数が呼び出されます。現在、受信したメッセージはログに記録されるだけです。
  - バックグラウンドとフォアグラウンドのメッセージの配信と処理の違いについては、Android アプリでメッセージを受信するをご覧ください。
また、AndroidManifest.xml では、StockNewsApplication という名前の Android Application クラスも提供されます。
- このクラスは、アプリの起動時に最初にインスタンス化されるクラスになります。
- StockNewsApplication クラスの onCreate 関数に、FCM 登録トークンの作成呼び出しが追加されています。有効な FCM 登録トークンが生成され、ログに記録されます。
MainActivity.java は、在庫カテゴリの選択肢を表示する RecyclerView を追加します。
SubscriptionAdapter.java は、在庫カテゴリ選択画面を描画する RecyclerView.Adapter を実装します。
- 各株カテゴリには名前と、その横に購読の切り替えボタンがあります。
- 切り替えを切り替えると、FCM トピックのサブスクリプション / サブスクライブ解除の呼び出しが行われるはずです。
- これらの呼び出しは、次のセクションで実装します。
model/StockCategories.java クラスには、すべての株価カテゴリとその関連トピック名のリストが含まれます。

スターターアプリを実行する

Android デバイスをパソコンに接続するか、エミュレータを起動します。
上部のツールバーで、ターゲットの Android デバイスまたはエミュレータを選択し、実行ボタンを押します。

アプリの UI は次のようになります。

アプリは FCM 登録トークンを作成してログに記録します。ただし、アプリの UI は変更されません。
1. FCM 登録トークンをコピーして保存します。これは次の手順で使用します。

5. テストメッセージを送信する

これで、前の手順で設定したアプリインスタンスにテストメッセージを送信する準備ができました。

スターターサーバーコードをインポートする

IntelliJ IDEA を起動して、messaging/fcm-topics-codelab/starter/StockNewsServer プロジェクトを開きます。

左側のナビゲーションバーのプロジェクトビューは次のようになります。

IntelliJ IDEA でプロジェクトをビルドする（必要な依存関係の取得を含む）には数分かかることがあります。

サーバーのスターターコードを理解する

サーバーのスターターコードは、Gradle ベースの Java プロジェクトです。
build.gradle ファイルには、firebase-admin SDK への依存関係がすでに追加されています。この SDK を使用すると、さまざまな FCM メッセージ送信機能にアクセスできます。

最後に、
- FcmSender.java: このクラスには、次のメソッドが含まれています。
  - initFirebaseSDK: firebase-admin SDK を初期化します。
  - sendMessageToFcmRegistrationToken: FCM 登録トークンにメッセージを送信します。
  - sendMessageToFcmTopic: FCM トピックにメッセージを送信します。
  - sendMessageToFcmTopicCondition: FCM トピック条件にメッセージを送信します。
- FcmSubscriptionManager.java: このクラスには、サーバーサイドからトピックのサブスクリプションを管理できるメソッドが含まれています。
  - initFirebaseSDK: firebase-admin SDK を初期化します。
  - subscribeFcmRegistrationTokensToTopic: FCM 登録トークンを FCM トピックに登録します。
  - unsubscribeFcmRegistrationTokensFromTopic: FCM トピックから FCM 登録トークンを登録解除します。

サーバーコードの設定

まず、firebase-admin SDK が FCM API への呼び出しを承認できるように、Firebase サービスアカウントを設定する必要があります。
1. Firebase コンソールに移動し、左側のナビゲーションバーの [プロジェクトの概要] の横にある歯車アイコンをクリックして、[プロジェクトの設定] を選択します。
2. 設定ページで、[サービスアカウント] を選択し、[サービスアカウントを作成] をクリックします。
3. [新しい秘密鍵を生成] ボタンをクリックすると、キーファイルの自動ダウンロードが開始されます。
4. キーファイルの名前を service-account.json に変更して、messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources フォルダにコピーします。
5. FcmSender.java と FcmSubscriptionManager.java はどちらも、次のコードを使用してクラスパスから service-account.json ファイルを読み込みます。
これで、サーバーコードの準備が整いました。上部のメニューバーから [Build] -> [Build Project] を実行します。

テストメッセージを送信する

FcmSender.java で sendMessageToFcmRegistrationToken 関数を見つけ、スターターアプリを実行するセクションからコピーした FCM 登録トークンを registrationToken フィールドに挿入します。
main 関数で、sendMessageToFcmRegistrationToken 関数のみのコメントを解除し、実行をクリックしてコードを実行します。
1. FCM 登録トークンが message オブジェクトの Token フィールドに設定されていることを確認します。
2. また、FirebaseMessaging インターフェースの send API を使用していることにも注目してください。

これにより、前のステップで設定したアプリインスタンスにメッセージが送信されます。
アプリインスタンスがフォアグラウンドにある場合、メッセージコンテンツがログに記録されます。

アプリインスタンスがバックグラウンドにある場合は、通知トレイにメッセージが表示されます。

Firebase Admin SDK を使用してアプリインスタンスにメッセージを送信しました。サーバーでの Firebase Admin SDK の使用について詳しくは、こちらをご覧ください。

6. トピックの登録 / 登録解除を実装する

このステップでは、Android アプリの [Stock Category] 切り替えで、トピックのサブスクリプションと登録解除のアクションを実装します。

アプリユーザーが特定の株カテゴリの切り替えを切り替えると、トピックの登録または登録解除の呼び出しが行われます。

コードを確認する

Android アプリのコードで SubscriptionAdapter.java クラスに移動し、RecyclerViewViewHolder クラスを見つけます。

クラスコンストラクタは、setOnCheckedChangeListener を使用してサブスクリプション切り替えのリスナーを設定します。
切り替えの切り替えに応じて、subscribeToStockCategory メソッドと unsubscribeFromStockCategory メソッドをそれぞれ呼び出すことで、登録と登録解除のアクションが実行されます。
setData メソッドは、RecyclerView アダプターの onBindViewHolder によって呼び出され、ViewHolder を適切な株価カテゴリにバインドします。

トピックのサブスクリプションを実装する

subscribeToStockCategory メソッドで、FirebaseMessaging オブジェクトの subscribeToTopic API の呼び出しを実装します。コードは次のようになります。

   void subscribeToStockCategory() {
      // Making call to FCM for subscribing to the topic for stockCategory
     FirebaseMessaging.getInstance().subscribeToTopic(stockCategory.getTopicName()).addOnSuccessListener(
          unused -> {
            // Subscribing action successful
            Log.i(TAG, "Subscribed to topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Subscribed to " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

トピックの登録解除を実装する

同様に、else 条件で unsubscribeFromTopic API の呼び出しを実装します。次のような行を追加します。

void unsubscribeFromStockCategory() {
      // Making call to FCM for unsubscribing from the topic for stockCategory
      FirebaseMessaging.getInstance().unsubscribeFromTopic(stockCategory.getTopicName())
          .addOnSuccessListener(unused -> {
            // Unsubscribing action successful
            Log.i(TAG, "Unsubscribed from topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Unsubscribed from " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

試してみましょう

アプリを実行し、[Stock Category] オプションを切り替えて、[Subscribe] アクションと [Unsubscribe] アクションを実行します。それは次のようになります。

登録	登録解除

7. 最初のトピックメッセージを送信する

このステップでは、FCM トピックメッセージを送信するサーバーサイドコードを実装します。

トピックメッセージを送信するためのサーバーサイド統合を実装する

サーバーコードで FcmSender.java に移動し、sendMessageToFcmTopic という名前のメソッドを探します。

1 行目に、メッセージの送信先となる FCM トピックを指定します。
- /topics/<Topic Name> の形式の文字列です。例: /topics/Technology
次の行で、新しい message オブジェクトを作成します（sendMessageToFcmRegistrationToken 関数で定義されたオブジェクトと同様）。
- 違いは、message オブジェクトの Token フィールドを設定する代わりに、Topic フィールドを設定することです。

Message message = Message.builder()
        .putData("FOOTECH", "$1000")
        .setNotification(
            Notification.builder()
                .setTitle("Investor confidence in Tech Stocks growing")
                .setBody("Foo Tech leading the way in stock growth for Tech sector.")
                .build())
        .setTopic(topicName)
        .build();

次に、FirebaseMessaging インスタンスの呼び出しを追加して、メッセージを送信します（sendMessageToFcmRegistrationToken 関数で行われた送信呼び出しと同じです）。

FirebaseMessaging.getInstance().send(message);

最後に、main 関数を更新し、sendMessageToFcmTopic 関数のみを呼び出せるようにします。

メッセージを送信して受信を確認する

トピックメッセージを送信する前に、アプリインスタンスが送信先のトピックに登録されていることを確認してください。
1. これは、対応する切り替えを切り替えることで行えます。例:
FcmSender.java の main 関数を実行して、トピックメッセージを送信できるようになりました。
以前と同様に、アプリインスタンスでメッセージの受信を確認できます。
1. フォアグラウンドのアプリインスタンス
1. バックグラウンドのアプリインスタンス
ボーナス: 送信先のトピックの登録を解除して、メッセージを再送信してみてください。メッセージがアプリインスタンスに配信されていないことがわかります。

8. 最初のトピック条件メッセージを送信する

トピック条件機能を使用すると、複数のトピックにメッセージを送信できるため、より表現力豊かなオーディエンス定義を提供できます。

たとえば、StockNews アプリでは、テクノロジートピックまたは自動車トピックのいずれかに登録しているアプリインスタンスのグループにメッセージを送信する可能性を検討します。たとえば、Waymo に関連する注目すべきイベントが発生した場合に、このようなケースが発生する可能性があります。

トピックでは、次の演算子を使用して、ブール式の形式で組み合わせを表現できます。

&& : 論理 AND。たとえば、'Technology' in topics && 'Automotive' in topics は、テクノロジーと自動車の両方のトピックを購読しているアプリインスタンスのみをターゲットにします。
|| : 論理 OR。たとえば、'Technology' in topics || 'Automotive' in topics - テクノロジートピックまたは自動車トピックのいずれかに登録されているアプリインスタンスをターゲットにします。
() : グループ化のためのかっこ。たとえば、'Technology' in topics && ('Automotive' in topics || 'Energy' in topics) - テクノロジーと自動車またはエネルギーのトピックを購読しているアプリインスタンスのみをターゲットにします。

この機能を使用するための送信リクエストの作成方法について詳しくは、こちらをご覧ください。

トピック条件メッセージを送信するためのサーバーサイド統合を実装

サーバーコードに戻り、FcmSender.java に移動して sendMessageToFcmTopicCondition という名前のメソッドを探します。

1 行目の topicCondition 変数に、メッセージの送信先となるトピック条件を指定します。'Technology' in topics && 'Automotive' in topics に設定できます。
次の行で、新しい message オブジェクトを作成します（sendMessageToFcmTopic 関数で定義されたものと同様）。
1. 違いは、オブジェクトの Topic フィールドを設定する代わりに、Condition フィールドを設定することです。

    Message message = Message.builder()
        .putData("FOOCAR", "$500")
        .setNotification(
            Notification.builder()
                .setTitle("Foo Car shows strong Q2 results")
                .setBody("Foo Car crosses 1B miles. Stocks rally.")
                .build())
        .setCondition(topicCondition)
        .build();

次に、FirebaseMessaging インスタンスの呼び出しを追加して、メッセージを送信します（sendMessageToFcmTopic 関数で行われた送信呼び出しと同じです）。

FirebaseMessaging.getInstance().send(message);

最後に、main 関数を更新し、sendMessageToFcmTopicCondition 関数のみを呼び出せるようにします。

メッセージを送信して受信を検証する

トピックメッセージを送信する前に、アプリインスタンスを Technology トピックと Automotive トピックの両方に登録して、アプリインスタンスが指定されたトピック条件を満たしていることを確認します。
FcmSender.java の main 関数を実行して、トピックメッセージを送信できるようになりました。
以前と同様に、アプリインスタンスでメッセージの受信を確認できます。
1. フォアグラウンドのアプリインスタンス
1. バックグラウンドのアプリインスタンス
ボーナス: これで、テクノロジートピックの登録を解除して、トピック条件メッセージを再送信できます。メッセージがアプリインスタンスで受信されないことを確認します。

9. まとめ

これまでの学習内容を簡単に振り返りましょう。

アプリインスタンスからトピックの登録 / 登録解除を開始する方法。
トピックにメッセージを送信し、登録されたアプリインスタンスで受信を確認します。
トピック条件にメッセージを送信し、条件を満たすアプリインスタンスで受信を確認する。

次のセクションでは、クライアント側から呼び出しをインスタンス化することなく、アプリインスタンスをトピックに登録 / 登録解除する方法について説明します。

10. サーバーサイドからトピックサブスクリプションを管理する

この Codelab では、これまで、トピックの登録と登録解除の呼び出しはすべてアプリインスタンスから開始されていました。

ただし、ユースケースによっては、サーバーサイドからトピックサブスクリプションを管理したい場合があります。たとえば、アプリのロールアウトを待たずに、既存のユーザーベースのサブグループを新しいトピックに登録したい場合があります。

このセクションでは、サーバーサイドから呼び出しを行うことで、FCM 登録トークンのバッチをトピックに登録または登録解除するために Firebase Admin SDK を使用する方法について説明します。

FCM 登録トークンの FCM トピックへのサーバーサイドサブスクリプションを実装する

サーバーコードで、FcmSubscriptionManager.java クラスに移動します。subscribeFcmRegistrationTokensToTopic という名前のメソッドを見つけます。ここでは、subscribeToTopic API の呼び出しを実装します。

アプリインスタンスを Energy トピックにサブスクライブしてみましょう。そのため、まず次の 2 つのフィールドにデータを入力します。
1. registrationTokens: トピックのサブスクリプションを作成する FCM 登録トークンを表す文字列のカンマ区切りリスト。
2. topicName: エネルギートピックのトピック名（/topics/Energy など）。
次の数行で、次のように呼び出しを実装します。

TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
        registrationTokens, topicName);

TopicManagementResponse を調べると、結果の統計情報の概要を確認できます。たとえば、getSuccessCount を使用して、正常に作成されたトピックサブスクリプションの数を出力します。

System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());

最後に、main 関数で、subscribeFcmRegistrationTokensToTopic 関数のみへの呼び出しを有効にします。

サブスクリプションを作成してトピックメッセージを送信する

これで、トピックサブスクリプションを作成してメッセージを送信する準備が整いました。
FcmSubscriptionManager.java クラスの main 関数を実行します。これにより、トピックのサブスクリプションが作成されます。
次に、メッセージを送信するコードを設定します。以前と同様に、
1. FcmSender.java で、sendMessageToFcmTopic 関数を見つけます。
2. topicName をエネルギートピック（/topics/Energy
3. Message オブジェクトを作成し、setTopic を使用してトピックをターゲットにします。
4. 最後に、main メソッドを更新して、sendMessageToFcmTopic 関数のみを有効にします。
FcmSender.java の main 関数を実行します。これにより、メッセージがアプリインスタンスに送信され、アプリで次のように確認できます。
1. フォアグラウンドのアプリインスタンス
1. バックグラウンドのアプリインスタンス

FCM 登録トークンの FCM トピックへのサーバーサイドの登録解除を実装

サーバーサイドのトピック登録解除には、この unsubscribeFromTopic API を使用します。関連するコードを FcmSubscriptionManager.java クラスの unsubscribeFcmRegistrationTokensFromTopic 関数に追加します。

サーバーサイドの登録解除コードを実装し、トピックメッセージを送信してその効果を検証することは、読者の練習問題として残されています。

11. 完了

おめでとうございます。FCM トピックを使用して、アプリインスタンスのサブグループにマルチキャストメッセージを送信できました。これにより、関連性の高いコンテンツをユーザーにタイムリーに届けやすくなります。

次のステップ

この Codelab を完了したら、次のガイドを使用して、他のプラットフォームのトピックを試してみてください。

リファレンスドキュメント

Android API リファレンス（Java / Kotlin）
iOS API リファレンス（ObjectiveC / Swift）
JavaScript API リファレンス（バージョン 9 / バージョン 8）
Admin SDK リファレンス（Node.js / Java / Python / .NET）