向多台设备发送消息（Apple 平台）

Firebase Cloud Messaging 提供了两种向多台设备发送消息的方法：

主题消息传递，允许您将消息发送至已经选择订阅特定主题的多台设备。
设备组消息传递，允许您将一条消息发送至在属于同一组的设备上运行的多个应用实例。

本教程主要介绍如何使用 Admin SDK 或 REST API 从应用服务器发送 FCM 主题消息，并在 Apple 应用中接收和处理此类消息。本页面列出了实现上述目标所需的所有步骤（从设置到验证）。如果您已针对 FCM 设置了 Apple 客户端应用，或已经完成发送第一条消息所需执行的步骤，您可能已经完成了本页面中的一些步骤。

将 Firebase 添加到您的 Apple 项目中

如果您已经为自己的应用启用了其他 Firebase 功能，那么您可能已经完成了本部分将要介绍的一些任务。您需要专门为 FCM 上传您的 APNs 身份验证密钥并注册接收远程通知。

前提条件

安装以下软件：
- Xcode 14.1 或更高版本
确保您的项目满足以下要求：
- 您的项目的目标平台不得低于以下版本：
  - iOS 11
  - macOS 10.13
  - tvOS 12
  - watchOS 6

设置一台 Apple 实体设备来运行您的应用，然后完成以下任务：
- 获取您的 Apple 开发者帐号的 Apple 推送通知身份验证密钥。
- 在 XCode 中通过 App（应用）> Capabilities（功能）启用推送通知功能。

使用您的 Google 帐号登录 Firebase。

如果您还没有 Xcode 项目，只是想试用某一 Firebase 产品，可以下载一个我们的快速入门示例。

创建 Firebase 项目

您需要先创建一个要关联到您的 Apple 应用的 Firebase 项目，然后才能将 Firebase 添加到该应用。如需详细了解 Firebase 项目，请访问了解 Firebase 项目。

创建 Firebase 项目

在 Firebase 控制台中，点击添加项目。
- 如需将 Firebase 资源添加到现有 Google Cloud 项目，请输入该项目的名称或从下拉菜单中选择该项目。
- 如需创建新项目，请输入要使用的项目名称。您也可以视需要修改项目名称下方显示的项目 ID。
  
  Firebase 会根据您提供的名称，为您的 Firebase 项目生成一个唯一 ID。如果您希望修改此项目 ID，必须立即修改，因为当 Firebase 为项目预配资源后，您将无法进行更改。如需详细了解 Firebase 如何使用项目 ID，请访问了解 Firebase 项目。
如果看到相关提示，请查看并接受 Firebase 条款。
点击继续。

（可选）为您的项目设置 Google Analytics（分析），以便在使用下列 Firebase 产品时能获得最佳体验：

选择现有的 Google Analytics（分析）帐号，或者创建一个新帐号。

如果您选择创建一个新帐号，请选择 Analytics（分析）报告位置，然后接受项目的数据共享设置和 Google Analytics（分析）条款。

点击创建项目（如果使用现有的 Google Cloud 项目，则点击添加 Firebase）。

Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后，您将进入 Firebase 控制台中 Firebase 项目的概览页面。

在 Firebase 中注册您的应用

如需在 Apple 应用中使用 Firebase，您需要在 Firebase 项目中注册您的应用。注册应用的过程通常称为将应用“添加”到项目中。

前往 Firebase 控制台。
在项目概览页面的中心位置，点击 iOS+ 图标，启动设置工作流。

如果您已向 Firebase 项目添加了应用，请点击添加应用以显示平台选项。
在软件包 ID 字段中输入应用的软件包 ID。
什么是软件包 ID，在哪里可以找到它？
- 软件包 ID 是应用在 Apple 生态系统中的唯一标识符。
- 如何找到您的软件包 ID：在 Xcode 中打开您的项目，在项目导航器中选择顶级应用，然后选择 General（常规）标签页。
  
  Bundle Identifier（软件包标识符）字段的值就是软件包 ID（例如 com.yourcompany.yourproject）。
- 请注意，软件包 ID 值区分大小写，此 Firebase 应用在您的 Firebase 项目中注册后，该值便无法更改。
请务必输入您的应用实际使用的软件包 ID。软件包 ID 值区分大小写，并且此 Firebase Apple 应用在您的 Firebase 项目中注册后，该值便无法更改。
（可选）输入其他应用信息：应用别名和 App Store ID。
应用别名和 App Store ID 在 Firebase 中的作用是什么？
- 应用别名：方便内部使用的标识符，只有您能在 Firebase 控制台中看到
- App Store ID：Firebase Dynamic Links 使用该 ID 将用户重定向到 App Store 页面，而 Google Analytics（分析）则用它将转化事件导入 Google Ads。如果您的应用还没有 App Store ID，您可以稍后在项目设置中添加此 ID。
点击注册应用。

添加 Firebase 配置文件

点击下载 GoogleService-Info.plist，获取 Firebase Apple 平台配置文件 (GoogleService-Info.plist)。
关于此配置文件，您需要了解哪些信息？
- 此 Firebase 配置文件包含项目的唯一但非机密的标识符。如需详细了解此配置文件，请访问了解 Firebase 项目。
- 您可以随时再次下载 Firebase 配置文件。
- 请确保该配置文件名未附加其他字符，如 (2)。
将配置文件移至 Xcode 项目的根目录中。如果出现提示，请选择将配置文件添加到所有目标。

如果您的项目中有多个软件包 ID，必须将每个软件包 ID 与 Firebase 控制台中的注册应用相关联，使每个应用都有自己的 GoogleService-Info.plist 文件。

将 Firebase SDK 添加至您的应用

使用 Swift Package Manager 安装和管理 Firebase 依赖项。

在 Xcode 中打开您的应用项目，依次点击 File（文件）> Add Packages（添加软件包）。
出现提示时，添加 Firebase Apple 平台 SDK 代码库：

  https://github.com/firebase/firebase-ios-sdk

选择 Firebase Cloud Messaging 库。
为了获得最佳的 Firebase Cloud Messaging 使用体验，我们建议您在 Firebase 项目中启用 Google Analytics（分析），并将 Firebase SDK for Google Analytics 添加到您的应用中。您可以选择不收集 IDFA 的库，也可以选择收集 IDFA 的库。
完成之后，Xcode 将会自动开始在后台解析和下载您的依赖项。

上传您的 APNs 身份验证密钥

将您的 APNs 身份验证密钥上传到 Firebase。如果您还没有 APNs 身份验证密钥，请务必在 Apple Developer Member Center 内创建一个。

在 Firebase 控制台中，在您的项目内依次选择齿轮图标 > 项目设置 > Cloud Messaging 标签页。
在 iOS 应用配置下的 APNs 身份验证密钥中，点击上传按钮。
转到您保存密钥的位置，选择该密钥，然后点击打开。添加该密钥的 ID（可在 Apple Developer Member Center 中找到），然后点击上传。

在您的应用中初始化 Firebase

您需要为应用添加 Firebase 初始化代码。请按如下所示导入 Firebase 模块并配置一个共享实例：

在 UIApplicationDelegate 中导入 FirebaseCore 模块，以及您的应用委托 (app delegate) 使用的所有其他 Firebase 模块。例如，如需使用 Cloud Firestore 和 Authentication，请添加以下代码：

SwiftUI

import SwiftUI
import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

Swift

import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

Objective-C

@import FirebaseCore;
@import FirebaseFirestore;
@import FirebaseAuth;
// ...

在应用委托的 application(_:didFinishLaunchingWithOptions:) 方法中配置一个 FirebaseApp 共享实例：

SwiftUI

// Use Firebase library to configure APIs
FirebaseApp.configure()

Swift

// Use Firebase library to configure APIs
FirebaseApp.configure()

Objective-C

// Use Firebase library to configure APIs
[FIRApp configure];

如果您使用的是 SwiftUI，则必须创建应用委托并通过 UIApplicationDelegateAdaptor 或 NSApplicationDelegateAdaptor 将其附加到 App 结构体。您还必须停用应用委托调配。如需了解详情，请参阅 SwiftUI 说明。

SwiftUI

@main
struct YourApp: App {
  // register app delegate for Firebase setup
  @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

注册接收远程通知

可在启动时或在应用流程中期望的时间点注册您的应用，以便接收远程通知。调用 registerForRemoteNotifications，如下所示：

注意：SwiftUI 应用应使用 UIApplicationDelegateAdaptor 或 NSApplicationDelegateAdaptor 属性封装容器来提供与相应应用委托协议对应的类型。

Swift


UNUserNotificationCenter.current().delegate = self

let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(
  options: authOptions,
  completionHandler: { _, _ in }
)

application.registerForRemoteNotifications()
AppDelegate.swift

Objective-C


[UNUserNotificationCenter currentNotificationCenter].delegate = self;
UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
    UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
[[UNUserNotificationCenter currentNotificationCenter]
    requestAuthorizationWithOptions:authOptions
    completionHandler:^(BOOL granted, NSError * _Nullable error) {
      // ...
    }];

[application registerForRemoteNotifications];AppDelegate.m

您必须分配 UNUserNotificationCenter 的 delegate 属性和 FIRMessaging 的 delegate 属性。例如，在 iOS 应用中，需在应用委托的 applicationWillFinishLaunchingWithOptions: 或 applicationDidFinishLaunchingWithOptions: 方法中对其进行分配。

为客户端应用订阅主题

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

如需订阅一个主题，请从应用的主线程中调用订阅方法（FCM 并不保证线程安全性）。如果初始订阅请求失败，FCM 会自动重试。对于无法完成订阅的情况，订阅会抛出一个错误，您可以在完成处理程序中捕获该错误，如下所示：

Swift

Messaging.messaging().subscribe(toTopic: "weather") { error in
  print("Subscribed to weather topic")
}ViewController.swift

Objective-C

[[FIRMessaging messaging] subscribeToTopic:@"weather"
                                completion:^(NSError * _Nullable error) {
  NSLog(@"Subscribed to weather topic");
}];ViewController.m

此调用会向 FCM 后端发出一个异步请求，并为该客户端订阅指定主题。在调用 subscribeToTopic:topic 之前，请确保客户端应用实例已通过回调函数 didReceiveRegistrationToken 收到注册令牌。

每次应用启动时，FCM 会确保请求的所有主题都已订阅。如需退订主题，请调用 unsubscribeFromTopic:topic，FCM 即会在后台中退订相关主题。

接收和处理主题消息

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

按如下所示实现 application(_:didReceiveRemoteNotification:fetchCompletionHandler:)：

Swift

func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async
  -> UIBackgroundFetchResult {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired till the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // Messaging.messaging().appDidReceiveMessage(userInfo)

  // Print message ID.
  if let messageID = userInfo[gcmMessageIDKey] {
    print("Message ID: \(messageID)")
  }

  // Print full message.
  print(userInfo)

  return UIBackgroundFetchResult.newData
}
AppDelegate.swift

Objective-C

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  // If you are receiving a notification message while your app is in the background,
  // this callback will not be fired till the user taps on the notification launching the application.
  // TODO: Handle data of notification

  // With swizzling disabled you must let Messaging know about the message, for Analytics
  // [[FIRMessaging messaging] appDidReceiveMessage:userInfo];

  // ...

  // Print full message.
  NSLog(@"%@", userInfo);

  completionHandler(UIBackgroundFetchResultNewData);
}AppDelegate.m

构建发送请求

创建主题后，您可以通过两种方法向主题发送消息：一种是在客户端为客户端应用实例订阅该主题，另一种是使用服务器 API。如果您是首次构建 FCM 发送请求，请参阅关于您的服务器环境和 FCM 的指南，了解重要的背景信息和设置信息。

在后端的发送逻辑中，按如下所述的方式指定所需的主题名称：

Node.js

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

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

// Send a message to devices subscribed to the provided topic.
getMessaging().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.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp 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.
getMessaging().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(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .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

后续步骤

您可以使用服务器为客户端应用实例订阅主题并执行其他管理任务。请参阅在服务器上管理主题订阅。
详细了解向多台设备发送消息的另一种方式 - 设备组消息传递