设置 Firebase Cloud Messaging 客户端应用 (Unity)

如需使用 Unity 编写跨平台 Firebase Cloud Messaging 客户端应用，请使用 Firebase Cloud Messaging API。Unity SDK 在 Android 和 Apple 平台中都可使用，但需要针对每个平台进行一些额外设置。

准备工作

前提条件

• 安装 Unity 2021 LTS 或更高版本。对 Unity 2020 的支持被视为已弃用，并将在下一个主要版本之后不再享受积极支持。更早的版本也可能兼容，但不享受积极支持。

• （仅限 Apple 平台）安装以下各项：

  • Xcode 13.3.1 或更高版本
  • CocoaPods 1.12.0 或更高版本

• 确保您的 Unity 项目满足以下要求：

  • 对于 iOS - 目标为 iOS 13 或更高版本
  • 对于 tvOS - 目标为 tvOS 13 或更高版本
  • 对于 Android - 目标 API 级别为 21 (Lollipop) 或更高版本

• 设置设备或使用模拟器运行 Unity 项目。

  • 对于 iOS 或 tvOS - 设置实体设备以运行您的应用，并完成以下任务：

    • 获取您的 Apple 开发者账号的 Apple 推送通知身份验证密钥。
    • 在 Xcode 中通过 App（应用）> Capabilities（功能）启用推送通知功能。

  • 对于 Android - 模拟器必须使用包含 Google Play 的模拟器映像。

• 使用您的 Google 账号登录 Firebase。

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

第 1 步：创建 Firebase 项目

您必须创建一个 Firebase 项目以关联到 Unity 项目，然后才能将 Firebase 添加到该 Unity 项目。请访问了解 Firebase 项目以了解详情。

创建 Firebase 项目

1. 在 Firebase 控制台中，点击添加项目。

   • 如需将 Firebase 资源添加到现有 Google Cloud 项目，请输入该项目的名称或从下拉菜单中选择该项目。

   • 如需创建新项目，请输入要使用的项目名称。您也可以视需要修改项目名称下方显示的项目 ID。

     Firebase 会根据您提供的名称，为您的 Firebase 项目生成一个唯一 ID。如果您希望修改此项目 ID，必须立即修改，因为当 Firebase 为项目预配资源后，您将无法进行更改。如需详细了解 Firebase 如何使用项目 ID，请访问了解 Firebase 项目。

2. 如果看到相关提示，请查看并接受 Firebase 条款。

3. 点击继续。

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

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Remote Config 个性化 Firebase A/B Testing

   选择现有的 Google Analytics 账号，或者创建一个新账号。

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

   您以后可以随时在 项目设置的集成标签页中设置 Google Analytics。

5. 点击创建项目（或者，如果您使用的是现有 Google Cloud 项目，则点击添加 Firebase）。

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

第 2 步：在 Firebase 中注册您的应用

您可以注册一个或多个应用或游戏，以便将其与 Firebase 项目关联。

如果您要发布在 iOS 和 Android 两种系统上运行的游戏，请在同一个 Firebase 项目中注册 Unity 项目的这两个 build 目标。如果您有多个指定了不同 iOS 软件包 ID 或 Android 应用 ID 的 build 变体，则必须在同一个 Firebase 项目中注册每个 build 变体。

1. 前往 Firebase 控制台。

2. 在项目概览页面的中心位置，点击 Unity 图标 () 以启动设置工作流。

   如果您已向 Firebase 项目添加了应用，请点击添加应用以显示平台选项。

3. 选择您要注册的 Unity 项目的 build 目标，甚至可以选择同时注册两个目标。

   注意：如果您现在只注册 Unity 项目的一个 build 目标，之后可以随时返回到设置工作流注册另一个 build 目标。

4. 输入 Unity 项目针对具体平台的 ID。

   • 对于 iOS - 在 iOS 软件包 ID 字段中输入您的 Unity 项目的 iOS ID。

   • 对于 Android - 在 Android 软件包名称字段中输入您的 Unity 项目的 Android ID。
     “软件包名称”和“应用 ID”这两个术语通常可互换使用。

   在哪里可以找到您的 Unity 项目 ID？

   在 Unity IDE 中打开您的 Unity 项目，然后前往每个平台的设置部分：

   • 对于 iOS - 前往构建设置 > iOS。

   • 对于 Android - 前往 Android > 播放器设置 > 其他设置。

   您的 Unity 项目的 ID 是软件包标识符的值（示例 ID：com.yourcompany.yourproject）。

   确保输入项目实际使用的 ID。此 ID 值区分大小写。当您在 Firebase 项目中注册这些 Firebase 应用后，此 ID 值无法再更改。

5. （可选）输入 Unity 项目针对具体平台的别名。
   这些别名是方便内部使用的标识符，只有您能在 Firebase 控制台中看到。

6. 点击注册应用。

第 3 步：添加 Firebase 配置文件

1. 在 Firebase 控制台设置工作流中，获取针对具体平台的 Firebase 配置文件。

   如果您要注册 Unity 项目的 iOS 和 Android 这两个 build 目标，则需要为这两个平台分别下载并添加配置文件。

   • 对于 iOS - 点击下载 GoogleService-Info.plist。

   • 对于 Android - 点击下载 google-services.json。

   关于此配置文件，您需要了解哪些信息？

   • 此 Firebase 配置文件包含项目的唯一但非机密的标识符。如需详细了解此配置文件，请访问了解 Firebase 项目。

   • 您可以随时再次下载 Firebase 配置文件。

   • 请确保该配置文件名未附加其他字符，如 (2)。

2. 打开 Unity 项目的 Project（项目）窗口，然后将您的配置文件移到 Assets 文件夹中。

3. 返回 Firebase 控制台，在设置工作流中，点击下一步。

第 4 步：添加 Firebase Unity SDK

1. 在 Firebase 控制台中，点击下载 Firebase Unity SDK，然后将此 SDK 解压缩到方便的位置。

   • 您可以随时再次下载 Firebase Unity SDK。

   • Firebase Unity SDK 不局限于特定平台。

2. 在您打开的 Unity 项目中，依次转到 Assets > Import Package > Custom Package。

3. 从解压缩的 SDK 中，选择您希望在应用中使用且受支持的 Firebase 产品。

   为了获得最佳的 Firebase Cloud Messaging 使用体验，我们建议您在项目中启用 Google Analytics。此外，在设置 Analytics 时，您还需要将适用于 Analytics 的 Firebase 软件包添加到您的应用中。

   已启用 Analytics

   • 添加适用于 Google Analytics 的 Firebase 软件包：FirebaseAnalytics.unitypackage
   • 添加适用于 Firebase Cloud Messaging 的软件包：FirebaseMessaging.unitypackage

   未启用 Analytics

   添加适用于 Firebase Cloud Messaging 的软件包：FirebaseMessaging.unitypackage

4. 在“Import Unity Package”窗口中，点击 Import。

5. 返回 Firebase 控制台，在设置工作流中，点击下一步。

重要提示：使用 iOS 版 Firebase Unity SDK 时，请勿停用方法调配。SDK 需要调配，如果禁止调配，关键的 Firebase 功能（如 FCM 令牌处理）将无法正常运行。

第 5 步：确认 Google Play 服务版本要求

Android 版 Firebase Unity SDK 需要使用 Google Play services。您必须先将 Google Play 服务更新为最新版本，然后才能使用该 SDK。

在应用的开头添加以下 using 语句和初始化代码。在调用 SDK 中的任何其他方法之前，您可在此代码段中检查 Google Play services 版本是否符合 Firebase Unity SDK 的要求，并视情况将其更新为相应版本。

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

您的 Unity 项目已注册，并配置为使用 Firebase。

请访问将 Firebase 添加到 Unity 项目，以便：

• 了解 Firebase Unity SDK 支持的 Firebase 产品。
• 为 Unity 项目设置桌面工作流。
• 排查已知问题。

上传您的 APNs 身份验证密钥以获取 Apple 支持

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

1. 在 Firebase 控制台中，在您的项目内依次选择齿轮图标 > 项目设置 > Cloud Messaging 标签页。

2. 在 iOS 应用配置下的 APNs 身份验证密钥中，点击上传按钮。

3. 转到您保存密钥的位置，选择该密钥，然后点击打开。添加该密钥的 ID（可在 Apple Developer Member Center 中找到），然后点击上传。

在 Apple 平台上启用推送通知

第 1 步：添加用户通知框架

1. 点击 Xcode 中的项目，然后从 Editor area（编辑区）中选择 General（通用）标签页。

2. 向下滚动到 Linked Frameworks and Libraries（关联的框架和库），然后点击 + 号按钮以添加框架。

3. 在出现的窗口中，滚动到 UserNotifications.framework，点击该条目，然后点击 Add（添加）。

第 2 步：启用推送通知

1. 点击 Xcode 中的项目，然后从 Editor area（编辑区）中选择 Capabilities（功能）标签页。

2. 将 Push Notifications（推送通知）切换为 On（启用）。

3. 向下滚动到 Background Modes（后台模式），然后将其切换为 On（启用）。

4. 从 Background Modes（后台模式）下选择 Remote notifications（远程通知）复选框。

初始化 Firebase Cloud Messaging

当为 TokenReceived 或 MessageReceived 事件添加处理程序时，Firebase Cloud Messaging 库将会初始化。

在初始化时，将为客户端应用实例请求一个注册令牌。应用将通过 OnTokenReceived 事件接收令牌，并应缓存该令牌以备以后使用。如果您希望针对此特定设备发送消息，则需要使用此令牌。

此外，如果您希望能够接收传入的消息，则需要注册 OnMessageReceived 事件。

整个设置过程如下所示：

public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
}

public void OnTokenReceived(object sender, Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

public void OnMessageReceived(object sender, Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

配置 Android 入口点 Activity

在 Android 上，Firebase Cloud Messaging 附带了自定义入口点 activity，用以替换默认的 UnityPlayerActivity。如果您使用的不是自定义入口点，则系统会自动进行此替换，无需您执行任何其他操作。不使用默认入口点 Activity 或提供自己的 Assets/Plugins/AndroidManifest.xml 的应用将需要额外的配置。

Android 上的 Firebase Cloud Messaging Unity 插件打包了两个附加文件：

• Assets/Plugins/Android/libmessaging_unity_player_activity.jar 包含一个名为 MessagingUnityPlayerActivity 的 Activity，该 Activity 会替代标准 UnityPlayerActivity。
• Assets/Plugins/Android/AndroidManifest.xml 会指示应用使用 MessagingUnityPlayerActivity 作为应用的入口点。

提供这些文件是因为默认的 UnityPlayerActivity 不处理 onStop、onRestart activity 生命周期转换或者实现 onNewIntent，而后者对于 Firebase Cloud Messaging 正确处理传入消息是必需的。

配置自定义入口点 Activity

如果您的应用没有使用默认的 UnityPlayerActivity，则您需要移除提供的 AndroidManifest.xml，并确保您的自定义 Activity 可正确处理 Android Activity 生命周期的所有转换（具体操作方法如下例所示）。如果您的自定义 Activity 扩展了UnityPlayerActivity，您可以改为扩展 com.google.firebase.MessagingUnityPlayerActivity，该类中实现了所有必要的方法。

如果您使用自定义 Activity 且未扩展 com.google.firebase.MessagingUnityPlayerActivity，则应在您的 Activity 中添加以下代码段：

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For older versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This ensures that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

新版本的 Firebase C++ SDK（7.1.0 及更高版本）使用 JobIntentService，这需要在 AndroidManifest.xml 文件中进行额外修改。

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

关于 Android 上的消息传递的注意事项

当应用没有运行而用户点按通知时，默认情况下消息不会通过 FCM 的内置回调进行传递。在这种情况下，消息载荷是通过用于启动应用的 Intent 接收的。

当应用在后台时，用户设备接收到的消息会将其通知字段的内容用于填充系统任务栏通知，但该通知内容并不会传输给 FCM。也就是说，FirebaseMessage.Notification 将为空。

总结：

应用状态	通知	数据	两者
前台	Firebase.Messaging.FirebaseMessaging.MessageReceived	Firebase.Messaging.FirebaseMessaging.MessageReceived	Firebase.Messaging.FirebaseMessaging.MessageReceived
背景	系统任务栏	Firebase.Messaging.FirebaseMessaging.MessageReceived	通知：系统任务栏 数据：intent 的 extras 属性。

防止自动初始化

FCM 会生成一个用于设备定位的注册令牌。生成令牌时，库会将标识符和配置数据上传到 Firebase。如果您希望在使用令牌之前能够明确地自行选择，则可以通过在配置时停用 FCM（如果是 Android，则还要停用 Analytics）来防止生成该令牌。如需执行此操作，请向 Apple 上的 Info.plist（不是 GoogleService-Info.plist）或 Android 上的 AndroidManifest.xml 添加一个元数据值：

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

如需重新启用 FCM，您可以执行运行时调用：

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

此值一经设置便会持久保存，不受应用重启的影响。

在 Android 上处理包含深层链接的消息

FCM 允许将包含深层链接的消息发送到您的应用中。如需接收包含深层链接的消息，您必须在为应用处理深层链接的 Activity 中添加一个新的 intent 过滤器，该 intent 过滤器应能捕获您的网域的深层链接。如果您的消息不包含深层链接，则不需要此配置。在 AndroidManifest.xml 中：

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

您也可以指定通配符以使 intent 过滤器更加灵活。例如：

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

当用户点按的通知包含指向您指定的架构和主机的链接时，您的应用将会启动含此 intent 过滤器的 Activity 来处理该链接。

后续步骤

设置客户端应用后，即可使用 Firebase 发送下行消息和主题消息。如需了解详情，请参阅对此功能进行了演示的快速入门示例。

如需向您的应用添加其他更高级的行为，请参阅从应用服务器发送消息的指南：

• 发送主题消息
• 向设备组发送消息
• 发送上行消息

请注意，您需要完成服务器实现才能利用这些功能。