1. はじめに
目標
この Codelab では、FCM トピックを使用してアプリ インスタンスのさまざまなサブグループに push メッセージをマルチキャストできるように、マルチプラットフォーム アプリを計測する方法について学習します。
完了すると、FCM インフラストラクチャを活用して、これらのサブグループや、サブグループに対するマルチキャスト プッシュ メッセージを管理できるようになります。
トピックの概要
トピックは、FCM インフラストラクチャでサポートされている方法で、メッセージを使用してアプリ インスタンスのサブグループにアクセスできます。
FCM には、メッセージを送信するための API や、これらのトピックのサブスクリプションを維持する API が用意されています。アプリ インスタンスとトピックの関連付けをトピックに関連付け、関連付けを解除する作業は、それぞれサブスクライブ、サブスクライブ解除と呼ばれます。
トピックは一般公開されているコンテンツに使用します。たとえば、最新の天気に関するメッセージなどです。ユーザーに機密性の高いメッセージを送信する場合は、Firebase Admin SDK を使用して複数のデバイスにメッセージをマルチキャストします。
トピックベースのマルチキャストは、スループット向けに最適化されています。
ラボの内容
- モバイルアプリからトピックにユーザーを登録(およびサブスクライブ解除)する方法。
- トピックを使用してマルチキャスト プッシュ メッセージを送信する方法。
- トピック条件を使用してトピックの組み合わせにメッセージを送信する方法。
- トピックのサブスクリプションをサーバー側で管理し、サブスクリプションやサブスクリプションの一括削除を行う方法。
作成するアプリの概要
- トピックのサブスクライブ/サブスクライブ解除を行い、トピックへの送信時にメッセージを受信する Android アプリ。
- Firebase Admin SDK を使用したサーバーサイドの統合。この 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 プロジェクトを作成する
- Firebase コンソールで [プロジェクトを追加] をクリックし、Firebase プロジェクトに StockNews という名前を付け、[続行] をクリックします。注: Firebase プロジェクトのプロジェクト ID を覚えておいてください(または、編集アイコンをクリックして、お好みのプロジェクト ID を設定してください)。
- Google アナリティクスの有効化はスキップできます。この Codelab では、このファイルは必要ありません。[続行] をクリックします。
- [プロジェクトの作成] をクリックします。
これで完了です。Firebase プロジェクトが作成されました。プロジェクト名をクリックしてコンソールを開くことができます。
3. プラットフォーム固有の Firebase アプリ構成
Firebase サポートを有効にするために必要なコード変更のほとんどは、作業中のプロジェクトにすでにチェックインされています。ただし、モバイル プラットフォームのサポートを追加するには:
- 目的のプラットフォームを Firebase プロジェクトに登録する。
- プラットフォーム固有の構成ファイルをダウンロードしてコードに追加します。
この Codelab では、Android Firebase アプリを追加します。
Android を設定する
- Firebase コンソールの左側のナビゲーション バーの上部にある設定歯車アイコンで [プロジェクトの設定] を選択し、[全般] ページの [マイアプリ] で [Android] アイコンをクリックします。
「」というダイアログが表示されます。
- 指定が必要な重要な値は、Android パッケージ名 です。
com.ticker.stocknews
に設定します。- ここで指定するパッケージ名は、StockNewsApp スターター コードの
AndroidManifest.xml
で指定されているパッケージ名と同じである必要があります。場所を確認または変更する手順は次のとおりです。- StockNewsApp ディレクトリで、
app/src/main/AndroidManifest.xml
ファイルを開きます。 manifest
要素で、package
属性の文字列値を見つけます。この値が Android パッケージ名です。
- StockNewsApp ディレクトリで、
- ここで指定するパッケージ名は、StockNewsApp スターター コードの
- 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 によりトラッキングされていないことを示すアラートが表示される場合もあります。その場合は、[無視] または右上の [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
という名前の AndroidApplication
クラスも用意されています。- このクラスは、アプリの起動時に最初にインスタンス化されます。
StockNewsApplication
クラスのonCreate
関数に、FCM 登録トークン作成呼び出しが追加されています。有効な FCM 登録トークンが生成され、ログに記録されます。
MainActivity.java
は、在庫カテゴリの選択肢を表示するRecyclerView
を追加します。SubscriptionAdapter.java
は、ストック カテゴリの選択画面を描画するRecyclerView.Adapter
を実装します。- 各株式カテゴリには名前が表示され、横に定期購入の切り替えボタンがあります。
- 切り替えボタンを変更すると、FCM トピックのサブスクリプション / サブスクリプション解除の呼び出しが行われます。
- これらの呼び出しは後のセクションで実装します。
model/StockCategories.java
クラスには、すべての株式カテゴリとそれに関連するトピック名のリストが含まれています。
スターター アプリを実行する
- Android デバイスをパソコンに接続するか、エミュレータを起動します。
- 上部のツールバーで、ターゲットの Android デバイスまたはエミュレータを選択し、実行ボタンを押します。
- アプリの UI は次のようになります。
- アプリが FCM 登録トークンを作成してログに記録します。ただし、アプリの UI に変更はありません。
- 次のステップで使用するため、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 サービス アカウントを設定する必要があります。
- Firebase コンソールに移動し、左側のナビゲーション バーで [Project Overview] の横にある歯車アイコンをクリックして、[Project settings] を選択します。
- 設定ページで [サービス アカウント] を選択し、[サービス アカウントを作成] をクリックします。
- [新しい秘密鍵を生成] ボタンをクリックすると、鍵ファイルの自動ダウンロードが開始されます。
- キーファイルの名前を
service-account.json
に変更し、messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources
フォルダにコピーします。 FcmSender.java
とFcmSubscriptionManager.java
はどちらも、次のコードを使用してクラスパスからservice-account.json
ファイルを読み込みます。
- これで、サーバーコードの準備が整いました。ビルドの実行 ->[Build Project] を選択します。
テスト メッセージの送信
FcmSender.java
でsendMessageToFcmRegistrationToken
関数を見つけ、スターターアプリを実行するセクションからコピーした FCM 登録トークンをregistrationToken
フィールドに挿入します。main
関数で、sendMessageToFcmRegistrationToken
関数のみのコメント化を解除し、[実行] をクリックしてコードを実行します。- FCM 登録トークンが
message
オブジェクトのToken
フィールドに設定されることを確認します。 - さらに、
FirebaseMessaging
インターフェースのsend
API がどのように使用されているかにも注目してください。
- FCM 登録トークンが
- これにより、前の手順で設定したアプリ インスタンスにメッセージが送信されます。
- アプリ インスタンスがフォアグラウンドにあると、メッセージの内容がログに記録されます。
- アプリ インスタンスがバックグラウンドにある場合は、通知トレイにメッセージが表示されます。
Firebase Admin SDK を使用して、アプリ インスタンスにメッセージを送信できました。詳しくは、サーバーで Firebase Admin SDK を使用するをご覧ください。
6. トピックのサブスクリプション / サブスクリプション解除を実装する
このステップでは、Android アプリの [Stock Category] 切り替えボタンで、トピックのサブスクリプションと登録解除のアクションを実装します。
アプリユーザーが特定の株式カテゴリの切り替えを切り替えると、トピックのサブスクリプションまたは登録解除の呼び出しが行われます。
コードを確認する
- Android アプリのコードで
SubscriptionAdapter.java
クラスに移動し、RecyclerViewViewHolder
クラスを見つけます。
- クラスのコンストラクタは、
setOnCheckedChangeListener
を使用して、定期購入の切り替えボタンのリスナーを設定します。 - スイッチの切り替えに応じて、
subscribeToStockCategory
メソッドとunsubscribeFromStockCategory
メソッドを呼び出して、登録アクションと登録解除アクションをそれぞれ実行します。 setData
メソッドは、RecyclerView アダプターのonBindViewHolder
によって呼び出され、ViewHolder を適切な Stock Category にバインドします。
トピック サブスクリプションを実装する
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
関数の呼び出しのみを有効にします。
メッセージを送信して受信を確認する
- トピック メッセージを送信する前に、まずアプリ インスタンスが送信先のトピックにサブスクライブされていることを確認します。
- 対応する切り替えボタンで切り替えます。例:
- これで、
FcmSender.java
のmain
関数を実行してトピック メッセージを送信できます。 - 前回と同様に、アプリ インスタンスでメッセージの受信を確認できるはずです。
- フォアグラウンドのアプリ インスタンス
- バックグラウンドのアプリ インスタンス
- 参考: 送信先のトピックの登録を解除して、メッセージを再送信してみてください。メッセージがアプリ インスタンスに配信されていないことがわかります。
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
関数で定義されたものと同様のもの)を作成します。- 違いは、オブジェクトの
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
関数を実行してトピック メッセージを送信できます。 - 以前と同様に、アプリ インスタンスでメッセージの受信を確認できます。
- フォアグラウンドのアプリ インスタンス
- バックグラウンドのアプリ インスタンス
- ボーナス: テクノロジー トピックの登録を解除し、トピック条件メッセージを再送信できるようになりました。アプリ インスタンスでメッセージが受信されないことがわかります。
9. まとめ
ここまで学んだ内容を簡単に振り返りましょう。
- アプリ インスタンスからトピックの登録 / 登録解除を開始する方法。
- トピックにメッセージを送信し、登録済みのアプリ インスタンスで受信を確認しています。
- トピックの条件にメッセージを送信し、条件を満たすアプリ インスタンスで受信を確認する
次のセクションでは、クライアントサイドから呼び出しをインスタンス化せずに、アプリ インスタンスをトピックにサブスクライブ / サブスクライブ解除する方法について説明します。
10. サーバーサイドからトピック サブスクリプションを管理する
これまで、この Codelab では、トピックのサブスクリプションと登録解除の呼び出しはすべて、アプリ インスタンスから開始していました。
ただし、ユースケースによっては、サーバーサイドからトピックのサブスクリプションを管理することが必要な場合があります。たとえば、アプリのロールアウトを待たずに既存のユーザーベースのサブグループを新しいトピックにサブスクライブできます。
このセクションでは、Firebase Admin SDK を使用して、サーバー側から呼び出しを行うことで、FCM 登録トークンのバッチをトピックに登録または登録解除する方法について説明します。
FCM 登録トークンの FCM トピックへのサーバーサイド サブスクリプションを実装する
- サーバーコードで、
FcmSubscriptionManager.java
クラスに移動します。subscribeFcmRegistrationTokensToTopic
という名前のメソッドを見つけます。ここでは、subscribeToTopic
API の呼び出しを実装します。
- アプリ インスタンスを Energy トピックにサブスクライブしましょう。そのためには、まず次の 2 つのフィールドのデータを指定します。
registrationTokens
: トピック サブスクリプションを作成する FCM 登録トークンを表す文字列のカンマ区切りリスト。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
関数を実行します。これにより、トピックのサブスクリプションが作成されます。- 次に、メッセージを送信するためのコードを設定します。以前と同様に、
FcmSender.java
で、sendMessageToFcmTopic
関数を見つけます。topicName
を Energy トピック(例:/topics/Energy
Message
オブジェクトを作成し、setTopic
を使用してトピックにターゲティングします。- 最後に、
main
メソッドを更新してsendMessageToFcmTopic
関数のみを有効にします。
FcmSender.java
のmain
関数を実行します。これにより、メッセージがアプリ インスタンスに送信され、次のようにアプリで確認できます。- フォアグラウンドのアプリ インスタンス
- バックグラウンドのアプリ インスタンス
FCM トピックへの FCM 登録トークンのサーバーサイドの登録解除を実装する
- サーバーサイドのトピックの登録解除には、この
unsubscribeFromTopic
API を使用します。関連するコードをFcmSubscriptionManager.java
クラスのunsubscribeFcmRegistrationTokensFromTopic
関数に追加します。
- サーバーサイドの登録解除コードを実装し、トピック メッセージを送信してその効果を検証する作業は、演習として残しておきます。
11. 完了
これで、FCM トピックを使用して、アプリ インスタンスのサブグループにマルチキャスト メッセージを送信できました。これにより、関連性の高いコンテンツをタイムリーにユーザーに届けやすくなります。
次のステップ
Codelab を修了したので、以下のガイドを使用して他のプラットフォームのトピックを試してみることをおすすめします。