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
ディレクトリにあります。スターター コードにアクセスする手順は次のとおりです。これには、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 によってトラッキングされていないというアラートが表示されることもあります。その場合は、[Ignore] をクリックします。または「X」をクリックします。(変更を Git リポジトリにプッシュバックすることはありません)。
[Android] ビューの場合は、プロジェクト ウィンドウの左上に次のような画像が表示されます。([Project] ビューの場合は、プロジェクトを展開すると同じ画像が表示されます)。
初めてバックグラウンドでプロジェクトをコンパイルする場合、数秒かかることがあります。その間、Android Studio の下部にあるステータスバーにスピナーが表示されます。
テストが完了するまで待ってから、コードを変更することをおすすめします。これにより、Android Studio は必要なコンポーネントをすべて取り込むことができます。
また、「reload for language changes to take effect?」というメッセージが表示された場合は、[はい]を選択します
エミュレータのセットアップ
Android Emulator のセットアップについてサポートが必要な場合は、アプリを実行するをご覧ください。
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
という名前の 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
プロジェクトを開きます。
左側のナビゲーション バーにプロジェクト ビューが次のように表示されます。
IntellIj IDEA によるプロジェクトのビルドには、必要な依存関係の pull などに数分かかることがあります。
サーバーのスターター コードを理解する
- サーバー スターター コードは 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 アプリの [株式カテゴリ] 切り替えボタンに、トピックのサブスクリプションと登録解除のアクションを実装します。
アプリユーザーが特定の株式カテゴリの切り替えを切り替えると、トピック サブスクリプションまたはサブスクリプション解除呼び出しが行われます。
コードを確認する
- 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(); }); }
試してみる
- アプリを実行し、ストック カテゴリ オプションを切り替えて、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
関数で行われた send 呼び出しと同じです)。
FirebaseMessaging.getInstance().send(message);
- 最後に、
main
関数を更新し、sendMessageToFcmTopic
関数のみの呼び出しを有効にします。
メッセージを送信して確認メッセージを確認する
- トピック メッセージを送信する前に、まずアプリ インスタンスが送信先のトピックにサブスクライブされていることを確認します。
- 対応する切り替えボタンで切り替えます。例:
- これで、
FcmSender.java
のmain
関数を実行してトピック メッセージを送信できるようになりました。 - 前と同じように、アプリ インスタンスでメッセージの受信を確認できるはずです。
- フォアグラウンドのアプリ インスタンス
- バックグラウンドのアプリ インスタンス
- 参考: 送信先のトピックの登録を解除して、メッセージを再送信してみてください。メッセージがアプリ インスタンスに配信されていないことがわかります。
8. 最初のトピック条件メッセージを送信しています
トピック条件機能を使用すると、トピックの組み合わせにメッセージを送信できるため、より表現力豊かなオーディエンス定義が可能になります。
たとえば、StockNews アプリで、テクノロジーまたは自動車のトピックに登録しているアプリ インスタンスのグループにメッセージを送信する可能性について考えてみましょう。たとえば、Waymo が関係する注目に値する出来事がある場合などです。
Topics では、次の演算子を使用して組み合わせをブール式の形式で表現できます。
- &&: 論理 AND。たとえば、
'Technology' in topics && 'Automotive' in topics
- Technology Topics と Automotive 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
関数で定義されたものと同様のもの)を作成します。- 違いは、オブジェクトの
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 を修了したので、以下のガイドを使用して他のプラットフォームのトピックを試してみることをおすすめします。