Android でのトピック メッセージング

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

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

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

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

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

クライアント アプリを既存のトピックに登録することも、新しいトピックを作成することもできます。クライアント アプリを新しいトピック名(Firebase プロジェクトにまだ存在していないトピック名)に登録すると、その名前の新しいトピックが FCM に作成され、その後すべてのクライアントはそのトピック名に登録できるようになります。

トピックに登録する場合、クライアント アプリは、FCM トピック名を指定して Firebase Cloud Messaging subscribeToTopic() を呼び出します。このメソッドは Task を返します。この戻り値により、完了リスナーは登録が正常に完了したかどうかを判断できます。

Java
Android

FirebaseMessaging.getInstance().subscribeToTopic("weather")
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                String msg = getString(R.string.msg_subscribed);
                if (!task.isSuccessful()) {
                    msg = getString(R.string.msg_subscribe_failed);
                }
                Log.d(TAG, msg);
                Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
            }
        });

Kotlin
Android

FirebaseMessaging.getInstance().subscribeToTopic("weather")
        .addOnCompleteListener { task ->
            var msg = getString(R.string.msg_subscribed)
            if (!task.isSuccessful) {
                msg = getString(R.string.msg_subscribe_failed)
            }
            Log.d(TAG, msg)
            Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
        }

登録解除する場合、クライアント アプリはトピック名で Firebase Cloud Messaging unsubscribeFromTopic() を呼び出します。

サーバーでトピック登録を管理する

Instance ID API を利用して、サーバー側から基本的なトピック管理タスクを行うことができます。クライアント アプリ インスタンスの登録トークンを取得すると、次の操作を行えます。

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

FCM は、他のダウンストリーム メッセージと同じようにトピック メッセージを配信します。

メッセージを受信するには、FirebaseMessagingService を拡張したサービスを使用します。このサービスは onMessageReceived コールバックと onDeletedMessages コールバックをオーバーライドする必要があります。メッセージは受信から 20 秒以内に処理されるようにします(Android Marshmallow では 10 秒)。時間ウィンドウは、onMessageReceived を呼び出す前に発生した OS の遅延に応じて短くなる場合があります。この時間が経過すると、Android O のバックグラウンド実行制限などの OS の各種動作によって、作業完了が妨げられる可能性があります。詳細については、メッセージの優先度の概要をご覧ください。

onMessageReceived はほとんどのメッセージ タイプに用意されていますが、次の例外があります。

  • アプリがバックグラウンドで動作しているときに配信された通知メッセージ。この場合、通知は端末のシステムトレイに配信されます。通知をユーザーがタップすると、デフォルトではアプリのランチャーが開きます。

  • バックグラウンドで受信されたときに通知とデータ ペイロードの両方を持つメッセージ。この場合、通知はデバイスの通知領域(システムトレイ)に配信され、データ ペイロードはランチャー アクティビティのインテントの追加部分で配信されます。

要約:

アプリの状態 通知 データ ペイロード 両方
フォアグラウンド onMessageReceived onMessageReceived onMessageReceived
バックグラウンド システムトレイ onMessageReceived 通知: システムトレイ
インテントの追加部分にあるデータ
メッセージ タイプについて詳しくは、通知とデータ メッセージをご覧ください。

アプリのマニフェストの編集

FirebaseMessagingService を使用するには、アプリのマニフェストに次の設定を追加する必要があります。

<service android:name=".java.MyFirebaseMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

通知の外観をカスタマイズするためのデフォルト値を設定することもお勧めします。通知ペイロード内に同等の値が設定されていなかった場合に適用されるカスタム デフォルト アイコンとカスタム デフォルト カラーを指定できます。

カスタム デフォルト アイコンとカスタムカラーを設定するには、次の行を application タグに追加します。

<!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
     See README(https://goo.gl/l4GJaQ) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />

Android には、以下の場合にカスタム デフォルト アイコンが表示されます。

  • Notifications Composer から送信されたすべての通知メッセージ。
  • 通知ペイロード内にアイコンが明示的に設定されていない通知メッセージ。

Android では、以下の場合にカスタム デフォルト カラーが使用されます。

  • Notifications Composer から送信されたすべての通知メッセージ。
  • 通知ペイロード内にカラーが明示的に設定されていない通知メッセージ。

カスタム デフォルト アイコンが設定されず、通知ペイロード内にもアイコンが設定されていない場合は、Android では白色でレンダリングされたアプリケーション アイコンが表示されます。

onMessageReceived のオーバーライド

FirebaseMessagingService.onMessageReceived メソッドをオーバーライドすると、受信した RemoteMessage オブジェクトに基づいて操作を行い、メッセージ データを取得できます。

Java
Android

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    // ...

    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: " + remoteMessage.getFrom());

    // Check if message contains a data payload.
    if (remoteMessage.getData().size() > 0) {
        Log.d(TAG, "Message data payload: " + remoteMessage.getData());

        if (/* Check if data needs to be processed by long running job */ true) {
            // For long-running tasks (10 seconds or more) use Firebase Job Dispatcher.
            scheduleJob();
        } else {
            // Handle message within 10 seconds
            handleNow();
        }

    }

    // Check if message contains a notification payload.
    if (remoteMessage.getNotification() != null) {
        Log.d(TAG, "Message Notification Body: " + remoteMessage.getNotification().getBody());
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}

Kotlin
Android

override fun onMessageReceived(remoteMessage: RemoteMessage?) {
    // ...

    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: ${remoteMessage?.from}")

    // Check if message contains a data payload.
    remoteMessage?.data?.isNotEmpty()?.let {
        Log.d(TAG, "Message data payload: " + remoteMessage.data)

        if (/* Check if data needs to be processed by long running job */ true) {
            // For long-running tasks (10 seconds or more) use Firebase Job Dispatcher.
            scheduleJob()
        } else {
            // Handle message within 10 seconds
            handleNow()
        }
    }

    // Check if message contains a notification payload.
    remoteMessage?.notification?.let {
        Log.d(TAG, "Message Notification Body: ${it.body}")
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}

onDeletedMessages のオーバーライド

場合によっては、FCM からメッセージが配信されないことがあります。これは、特定の端末が接続されたときにその端末にまだ配信されていないアプリのメッセージが多すぎる(100 件を超えている)場合や、端末が 1 か月以上 FCM に接続されていない場合に起こります。このような場合、FirebaseMessagingService.onDeletedMessages() へのコールバックを受け取ることがあります。アプリ インスタンスがこのコールバックを受け取った場合は、アプリサーバーとの完全な同期を実行する必要があります。過去 4 週間以内にその端末のアプリにメッセージを送信していない場合、onDeletedMessages() は呼び出されません。

バックグラウンド アプリの通知メッセージの処理

アプリがバックグラウンドで動作しているとき、Android ではシステムトレイに通知メッセージが送られます。ユーザーが通知をタップすると、デフォルトでアプリ ランチャーが開きます。

通知とデータ ペイロードの両方を含むメッセージ(および Notifications コンソールから送信されたすべてのメッセージ)がここに含まれます。この場合、通知は端末の通知領域(システムトレイ)に配信され、データ ペイロードはランチャー アクティビティのインテントの追加部分で配信されます。

アプリへのメッセージ配信については、FCM レポート ダッシュボードをご覧ください。このダッシュボードには、Android アプリの「インプレッション」(ユーザーが表示した通知)のデータとともに、iOS と Android のデバイスで送信および開封されたメッセージの数が記録されています。

バックグラウンドでの使用が制限されたアプリ(Android P 以降)

2019 年 1 月からは、ユーザーが([設定] -> [アプリと通知] -> [appname] -> [電池] などから)バックグラウンドでの使用を制限したアプリに FCM のメッセージが配信されなくなります。バックグラウンドでの使用の制限が解除されると、アプリへの新しいメッセージが以前のように配信されます。バックグラウンドでの使用が制限されると、メッセージが失われるなど、さまざまな影響が生じるため、Android Vitals に表示される不適切な動作を避けるようにしてください。これらの動作は、Android デバイスがアプリのバックグラウンドでの使用を制限するようユーザーに推奨する原因になります。アプリのバックグラウンドでの使用が制限されているかどうかを確認するには、isBackgroundRestricted() を使用します。

送信リクエストを作成する

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

複数のトピックの組み合わせに送信する場合、アプリサーバーは condition キーに、対象のトピックを指定するブール条件を設定します。たとえば、TopicA と、TopicB または TopicC のいずれかに登録されたデバイスにメッセージを送信する場合には、次のようになります。

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM はまず、かっこ内の条件を評価し、次に左から右に式を評価していきます。上記の式では、いずれか 1 つのトピックだけに登録したユーザーはメッセージを受信しません。同様に、TopicA に登録していないユーザーはメッセージを受信しません。メッセージを受信するのは、次の組み合わせの場合のみです。

  • TopicA と TopicB
  • TopicA と TopicC

条件式には最大 5 つのトピックを含めることができ、かっこを使用できます。使用できる演算子は &&||! です。! の使用方法に注意してください。

!('TopicA' in topics)

この式では、どのトピックにも登録されていないアプリ インスタンスを含め、TopicA に登録されていないアプリ インスタンスすべてがメッセージを受信します。

アプリサーバーのキーの詳細については、リファレンス情報をご覧ください。

トピック HTTP POST リクエスト

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

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

次の cURL で送信します。

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

「犬」('dogs')または「猫」('cats')のトピックに登録されたデバイスに送信します。

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

次の cURL で送信します。

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

トピック HTTP レスポンス

{
    "name": "projects/myproject-b5ae1/messages/5735743068807585451"
}

メッセージ オプションの完全なリストについては、HTTP v1 API リファレンスをご覧ください。

次のステップ

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

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