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

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

1. はじめに

目標

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

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

Topics の概要

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

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

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

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

ラボの内容

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

作成するアプリの概要

トピックのサブスクライブ/サブスクライブ解除を行い、トピックへの送信時にメッセージを受信する Android アプリ。
Firebase Admin SDK を使用したサーバーサイドの統合。この SDK は、FCM API を介してトピックメッセージを送信するために使用されます。

必要なもの

任意のブラウザ（Chrome など）。
IntelliJ IDEA IDE（Java アプリケーション開発用）。
- インストールの際には、必ず 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 ディレクトリにあります。スターターコードにアクセスする手順は次のとおりです。2 つのディレクトリ StockNewsApp と StockNewsServer が含まれています。前者にはスターター Android アプリが含まれ、後者にはスターターサーバー側コードが含まれています。

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

この Codelab の完成版は messaging/fcm-topics-codelab/completed ディレクトリにあります。

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

Firebase コンソールで [プロジェクトを追加] をクリックし、Firebase プロジェクトに「StockNews」という名前を付けて [続行] をクリックします。注: Firebase プロジェクトのプロジェクト ID を覚えておいてください（または、[編集] アイコンをクリックして、使用するプロジェクト ID を設定します）。

Google アナリティクスの有効化をスキップできます。この Codelab では、必須ではありません。[続行] をクリックします。
[プロジェクトの作成] をクリックします。

これで完了です。これで 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?」というメッセージが表示された場合は、[はい]を選択します

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

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

Android アプリのスターターコードを理解する

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

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 プロジェクトを開きます。

左側のナビゲーションバーにプロジェクトビューが次のように表示されます。

必要な依存関係の pull など、IntelliJ IDEA でプロジェクトがビルドされるまでに数分かかることがあります。

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

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

最後に、次の 2 つのクラスがあります。
- 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 コンソールに移動し、左側のナビゲーションバーで [Project Overview] の横にある歯車アイコンをクリックして、[Project settings] を選択します。
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();
          });
    }

試してみましょう

アプリを実行し、株式カテゴリオプションを切り替えて、登録と登録解除のアクションを実行します。それは次のようになります。

登録	登録解除

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 関数で行われた send 呼び出しと同じです）。

FirebaseMessaging.getInstance().send(message);

最後に、main 関数を更新し、sendMessageToFcmTopic 関数のみの呼び出しを有効にします。

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

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

8. 最初のトピック条件メッセージを送信しています

トピック条件機能を使用すると、複数のトピックにメッセージを送信できるため、より柔軟なオーディエンスの定義が可能になります。

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

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

&&: 論理 AND。たとえば、'Technology' in topics && 'Automotive' in topics は、Technology トピックと Automotive トピックの両方に登録されているアプリインスタンスのみをターゲットにします。
|| : 論理 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 関数で行う send 呼び出しと同じです）。

FirebaseMessaging.getInstance().send(message);

最後に、main 関数を更新し、sendMessageToFcmTopicCondition 関数のみの呼び出しを有効にします。

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

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

9. まとめ

ここまで学んだ内容を簡単に振り返りましょう。

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

次のセクションでは、クライアントサイドから呼び出しをインスタンス化せずに、アプリインスタンスをトピックにサブスクライブ / サブスクライブ解除する方法について説明します。

10. サーバーサイドからトピック登録を管理する

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

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

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

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 を Energy トピック（例:/topics/Energy
3. Message オブジェクトを作成し、setTopic を使用してトピックをターゲットとします。
4. 最後に、sendMessageToFcmTopic 関数のみを有効にするように main メソッドを更新します。
FcmSender.java の main 関数を実行します。これにより、メッセージがアプリインスタンスに送信され、アプリで次のように確認できます。
1. フォアグラウンドのアプリインスタンス
1. バックグラウンドのアプリインスタンス

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

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

サーバーサイドの登録解除コードを実装し、トピックメッセージを送信してその効果を検証する作業は、演習として残しておきます。

11. 完了

これで、FCM トピックを使用してアプリインスタンスのサブグループにマルチキャストメッセージを送信できました。これにより、関連性の高いコンテンツをタイミングよくユーザーに表示することができます。

次のステップ

Codelab を修了したので、以下のガイドを使用して他のプラットフォームのトピックを試してみることをおすすめします。

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

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