Android 上的主题消息传递

基于其发布/订阅的模式，FCM 主题消息传递功能可让您将消息发送至已经选择加入特定主题的多台设备。您根据需要撰写主题消息，FCM 负责确定发布路径并将消息可靠地传送至正确的设备。

例如，某个本地潮汐预报应用的用户可选择加入“潮汐警报”主题，并接收关于特定区域最佳海水捕鱼条件的通知。体育应用的用户可以订阅他们心仪球队的实时比分自动更新。

关于主题，请注意以下事项：

• 主题消息传递最适合传递天气或其他可通过公开途径获得的信息。
• 主题消息的优化重心是吞吐量而非延迟。要将消息快速安全地传送到单台设备或小规模设备组，应将消息定位至注册令牌，而非主题。
• 如果您需要向一位用户的多台设备发送消息，请考虑为这些用例使用设备组消息传递。
• 主题消息传递不限制每个主题的订阅数。但是，FCM 在这些方面有强制性限制：
  • 一个应用实例不可订阅超过 2000 个主题。
  • 如果您正在使用批量导入来订阅应用实例，则每次请求仅限订阅 1000 个应用实例。
  • 每个项目新订阅频率的速率受限。如果您在短时间内发送过多订阅请求，FCM 服务器将给出 429 RESOURCE_EXHAUSTED（“已超出配额”）响应。使用指数退避重试。

为客户端应用订阅主题

客户端应用可以订阅任何现有主题，也可创建新主题。当客户端应用订阅新的主题名称（您的 Firebase 项目中尚不存在）时，系统会在 FCM 中使用这个名称创建一个新主题，随后任何客户端都可订阅该主题。

若要订阅某个主题，客户端应用需使用 FCM 主题名称调用 Firebase 云消息传递的 subscribeToTopic() 方法。此方法会返回一个 Task，完成侦听器可以使用它来确定订阅是否成功：

Java

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();
            }
        });
MainActivity.java

Kotlin

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()
        }
MainActivity.kt

若要退订，客户端应用需使用主题名称调用 Firebase 云消息传递的 unsubscribeFromTopic() 方法。

在服务器上管理主题订阅

借助 Firebase Admin SDK 和 Google Instance ID API，您可以从服务器端执行基本的主题管理任务。如果有客户端应用实例的注册令牌，您还可以使用服务器逻辑批量订阅和退订这些实例。

您可以为客户端应用实例订阅任何现有主题，也可创建新主题。当您使用 API 为客户端应用订阅新主题（您的 Firebase 项目中尚不存在的名称）时，系统会在 FCM 中使用这个名称创建一个新主题，随后任何客户端都可订阅该主题。

使用 Firebase Admin SDK 订阅和退订主题

您可以将注册令牌列表传递给 Firebase Admin SDK 订阅方法，以便为相应的设备订阅主题：

Node.js

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Subscribe the devices corresponding to the registration tokens to the
// topic.
admin.messaging().subscribeToTopic(registrationTokens, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully subscribed to topic:', response);
  })
  .catch(function(error) {
    console.log('Error subscribing to topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Subscribe the devices corresponding to the registration tokens to the
// topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were subscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Subscribe the devices corresponding to the registration tokens to the
# topic.
response = messaging.subscribe_to_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were subscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Subscribe the devices corresponding to the registration tokens to the
// topic.
response, err := client.SubscribeToTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were subscribed successfully")

利用 Admin FCM API，您还可以通过将注册令牌传递给相应的方法来为设备退订主题：

Node.js

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
admin.messaging().unsubscribeFromTopic(registrationTokens, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully unsubscribed from topic:', response);
  })
  .catch(function(error) {
    console.log('Error unsubscribing from topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().unsubscribeFromTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were unsubscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Unubscribe the devices corresponding to the registration tokens from the
# topic.
response = messaging.unsubscribe_from_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were unsubscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
response, err := client.UnsubscribeFromTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were unsubscribed successfully")

注意：在单个请求中，您最多可以为 1000 台设备订阅或退订主题。如果您提供的一组注册令牌数量超过 1000 个，则此请求将失败并显示 messaging/invalid-argument 错误。

subscribeToTopic() 和 unsubscribeFromTopic() 方法会返回一个包含 FCM 响应的对象。无论请求中指定的注册令牌的数量为何，返回类型的格式都是相同的。

如果出现错误（身份验证失败、令牌或主题无效等），这些方法会返回错误。如需错误代码的完整列表（包括说明和解决步骤），请参阅 Admin FCM API 错误。

重要提示：要使用 Admin FCM API，您必须先按照将 Firebase Admin SDK 添加到您的服务器中所述的步骤来初始化该 SDK。

使用 Instance ID API 订阅和退订主题

Google Instance ID API 可用于进行以下主题管理任务：

• 查阅与客户端应用实例的订阅相关的详细信息，包括每个主题名称和订阅日期。请参阅获取应用实例相关信息。

• 为单个应用实例订阅或退订某主题。请参阅为应用实例创建关系映射。

• 为多个应用实例订阅或退订某主题。请参阅管理多个应用实例的关系映射。

接收和处理主题消息

FCM 传送主题消息的方式与处理其他下行消息的方式相同。

要接收消息，请使用继承 FirebaseMessagingService 的服务。您的服务应该重写 onMessageReceived 和 onDeletedMessages 回调方法。在收到任何消息后，该服务都应在 20 秒内处理消息（Android Marshmallow 上为 10 秒）。取决于调用 onMessageReceived 之前发生的操作系统延迟，时间窗口可能会更短。超过此时间之后，各种操作系统行为（如 Android O 的后台执行限制）可能会影响您完成工作的能力。如需了解详情，请参阅我们的消息优先级概述。

大多数类型的消息都会提供 onMessageReceived，但以下情况例外：

• 当应用在后台时送达的通知消息。在这种情况下，通知将传送至设备的系统任务栏。默认情况下，用户点按通知即可打开应用启动器。

• 当应用在后台时同时具备通知和数据负载的消息。在这种情况下，通知将传送至设备的系统任务栏，数据有效负载则传送至启动器 Activity 的 intent 的 extras 字段中。

汇总：

应用状态	通知	数据	两者
前台	onMessageReceived	onMessageReceived	onMessageReceived
后台	系统任务栏	onMessageReceived	通知：系统任务栏 数据：intent 的 extras 字段。

如需了解消息类型的详细信息，请参阅通知和数据消息。

对于提供了 onMessageReceived 的所有消息，您的服务应在收到消息后 20 秒内对其进行处理（在 Android Marshmallow 上为 10 秒）。取决于调用 onMessageReceived 之前发生的操作系统延迟，时间窗口可能会更短。超过此时间之后，各种操作系统行为（如 Android O 的后台执行限制）可能会影响您完成工作的能力。如需了解详情，请参阅我们的消息优先级概述。

修改应用清单文件

如需使用 FirebaseMessagingService，您需要将以下内容添加到您的应用清单：

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

此外，建议您设置默认值以便自定义通知的外观。您可以指定自定义默认图标和自定义默认颜色，以便在通知有效负载中未设置等效值时使用。

将以下代码行添加到 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" />
AndroidManifest.xml

对于以下内容，Android 会显示自定义默认图标：

• 从通知编辑器发送的所有通知信息。
• 在通知负载中未明确设置图标的任何通知消息。

对于以下内容，Android 会使用自定义的默认颜色：

• 从通知编辑器发送的所有通知信息。
• 在通知负载中未明确设置颜色的任何通知消息。

如果未设置自定义默认图标，而且通知负载中也未设置图标，Android 会显示以白色渲染的应用图标。

重写 onMessageReceived

通过重写 FirebaseMessagingService.onMessageReceived 方法，您可以根据收到的 RemoteMessage 对象执行操作并获取消息数据：

Java

@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 WorkManager.
            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.
}
MyFirebaseMessagingService.java

Kotlin

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 WorkManager.
            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.
}
MyFirebaseMessagingService.kt

重写 onDeletedMessages

在某些情况下，FCM 可能不会传递消息。如果在特定设备连接 FCM 时，您的应用在该设备上的待处理消息过多（超过 100 条），或者如果设备超过一个月未连接到 FCM，就会发生这种情况。在这些情况下，您可能会收到对 FirebaseMessagingService.onDeletedMessages() 的回调。当应用实例收到此回调时，应该执行一次与应用服务器的完全同步。如果您在过去 4 周内未向该设备上的应用发送消息，FCM 将不会调用 onDeletedMessages()。

在后台应用中处理通知消息

当您的应用位于后台时，Android 会将通知消息转发至系统任务栏。默认情况下，用户点按通知时将打开应用启动器。

这包括同时含有通知和数据有效负载的消息（以及从通知控制台发送的所有消息）。在这些情况下，通知将传送至设备的系统任务栏，数据有效负载则传送至启动器 Activity 的 intent 的 extras 字段。

有关发送到您应用的消息的详细情况，请参阅 FCM 报告信息中心，该信息中心记录在 iOS 和 Android 设备上发送和打开的消息数量，以及 Android 应用的“展示次数”（用户看到的通知）数据。

后台受限应用（Android P 或更高版本）

从 2019 年 1 月开始，FCM 将不会向由用户置于后台限制的应用传送消息（例如，通过“设置”->“应用和通知”->“[appname]”->“电池”）。一旦您的应用解除了后台限制，系统就会像以前一样向该应用传送新消息。为了防止消息丢失以及其他后台限制影响，一定要避免 Android Vitals 计划中列出的不良行为。这些行为可能会导致 Android 设备向用户建议将您的应用置于后台限制。您的应用可以使用 isBackgroundRestricted() 方法检查其是否受到后台限制。

构建发送请求

您创建一个主题后，可以通过两种方法向主题发送消息：一是在客户端为客户端应用实例订阅主题，二是通过服务器 API。在后端的发送逻辑中，按如下所示指定所需的主题名称：

Node.js

// The topic name can be optionally prefixed with "/topics/".
var topic = 'highScores';

var message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
admin.messaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Go

// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

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

如需向主题组合发送消息，请指定一个条件，即指定目标主题的布尔表达式。例如，以下条件会将消息发送至已订阅 TopicA 以及 TopicB 或 TopicC 的设备：

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

FCM 首先对括号中的所有条件求值，然后从左至右对表达式求值。在上述表达式中，只订阅某个单一主题的用户将不会接收到消息。同样地，未订阅 TopicA 的用户也不会接收到消息。下列组合将会接收到消息：

• TopicA 和 TopicB
• TopicA 和 TopicC

您最多可以在条件表达式中包括五个主题。

向条件发送消息：

Node.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = {
  notification: {
    title: '$GOOG up 1.43% on the day',
    body: '$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
admin.messaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(new Notification(
        "$GOOG up 1.43% on the day",
        "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day."))
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Go

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

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

后续步骤

• 详细了解向多台设备发送消息的另一种方式 - 设备组消息传递