获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

使用 Unity 设置 Firebase 云消息传递客户端应用

要使用 Unity 编写跨平台 Firebase 云消息传递客户端应用程序,请使用Firebase 云消息传递API。 Unity SDK 适用于 Android 和 Apple,每个平台都需要一些额外的设置。

在你开始之前

先决条件

  • 安装 Unity 2019.1 或更高版本。早期版本也可能兼容,但不会得到积极支持。对 Unity 2019.1 的支持被视为已弃用,下一个主要版本后将不再提供积极支持。

  • (仅限 iOS)安装以下内容:

    • Xcode 13.3.1 或更高版本
    • CocoaPods 1.10.0 或更高版本
  • 确保您的 Unity 项目满足以下要求:

    • 对于 iOS — 针对 iOS 11 或更高版本
    • 对于 Android——目标 API 级别 19 (KitKat) 或更高
  • 设置设备或使用模拟器来运行您的 Unity 项目。

    • 对于 iOS — 设置物理 iOS 设备来运行您的应用程序,并完成以下任务:

      • 为您的Apple Developer 帐户获取 Apple Push Notification Authentication Key。
      • App > Capabilities下的 XCode 中启用推送通知。
    • 对于 Android模拟器必须使用带有 Google Play 的模拟器图像。

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

第 1 步:创建一个 Firebase 项目

在将 Firebase 添加到 Unity 项目之前,您需要创建一个 Firebase 项目以连接到您的 Unity 项目。访问了解 Firebase 项目以了解有关 Firebase 项目的更多信息。

第 2 步:向 Firebase 注册您的应用

您可以注册一个或多个应用程序或游戏来连接您的 Firebase 项目。

  1. 转到Firebase 控制台

  2. 在项目概览页面的中央,单击Unity图标 ( ) 以启动设置工作流。

    如果您已将应用程序添加到 Firebase 项目,请单击添加应用程序以显示平台选项。

  3. 选择您要注册的 Unity 项目的构建目标,或者您甚至可以选择现在同时注册两个目标。

  4. 输入您的 Unity 项目的平台特定 ID。

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

    • 对于 Android — 在Android 包名称字段中输入您的 Unity 项目的 Android ID。
      术语包名称应用程序 ID经常互换使用。

  5. (可选)输入您的 Unity 项目的平台特定昵称。
    这些昵称是内部的、方便的标识符,并且仅在 Firebase 控制台中对您可见。

  6. 单击注册应用程序

第 3 步:添加 Firebase 配置文件

  1. 在 Firebase 控制台设置工作流程中获取特定于平台的 Firebase 配置文件。

    • 对于 iOS — 单击下载 GoogleService-Info.plist

    • 对于 Android — 单击下载 google-services.json

  2. 打开 Unity 项目的项目窗口,然后将配置文件移动到Assets文件夹中。

  3. 返回 Firebase 控制台,在设置工作流程中,单击下一步

第 4 步:添加 Firebase Unity SDK

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

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

    • Firebase Unity SDK 不特定于平台。

  2. 在您打开的 Unity 项目中,导航到Assets > Import Package > Custom Package

  3. 从解压缩的 SDK 中,选择您要在您的应用中使用的受支持的 Firebase 产品

    为了获得 Firebase 云消息传递的最佳体验,我们建议在您的项目中启用 Google Analytics 。此外,作为设置 Analytics 的一部分,您需要将用于 Analytics 的 Firebase 包添加到您的应用程序。

    启用分析

    • 为 Google Analytics 添加 Firebase 包: FirebaseAnalytics.unitypackage
    • 添加 Firebase Cloud Messaging 包: FirebaseMessaging.unitypackage

    未启用分析

    添加 Firebase Cloud Messaging 包: FirebaseMessaging.unitypackage

  4. 在“导入 Unity 包”窗口中,单击“导入”。

  5. 返回 Firebase 控制台,在设置工作流程中,单击下一步

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

适用于 Android 的 Firebase Unity SDK 需要Google Play 服务,该服务必须是最新的才能使用 SDK。

在应用程序的开头添加以下代码。在调用 SDK 中的任何其他方法之前,您可以检查并选择将 Google Play 服务更新到 Firebase Unity SDK 所需的版本。

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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。

第 7 步:添加用户通知框架

  1. 单击 Xcode 中的项目,然后从编辑器区域选择常规选项卡。

  2. 向下滚动到Linked Frameworks and Libraries ,然后单击+按钮添加一个框架。

  3. 在出现的窗口中,滚动到UserNotifications.framework ,单击该条目,然后单击Add

第 8 步:启用推送通知

  1. 单击 Xcode 中的项目,然后从Editor 区域中选择Capabilities选项卡。

  2. 将推送通知切换为

  3. 向下滚动到“背景模式”,然后将其切换到“开”

  4. 选择背景模式下的远程通知复选框。

初始化 Firebase 云消息传递

在为TokenReceivedMessageReceived事件添加处理程序时,将初始化 Firebase 云消息库。

初始化时,会为客户端应用程序实例请求注册令牌。应用程序将通过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 捆绑了一个自定义入口点活动,该活动取代了默认的UnityPlayerActivity 。如果您没有使用自定义入口点,则此替换会自动发生,您不必采取任何其他操作。不使用默认入口点 Activity 或提供自己的Assets/Plugins/AndroidManifest.xml的应用程序将需要额外配置。

Android 上的 Firebase Cloud Messaging Unity 插件捆绑了两个附加文件:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar包含一个名为MessagingUnityPlayerActivity的活动,它取代了标准的UnityPlayerActivity
  • Assets/Plugins/Android/AndroidManifest.xml指示应用程序使用MessagingUnityPlayerActivity作为应用程序的入口点。

提供这些文件是因为默认的UnityPlayerActivity不处理onStoponRestart活动生命周期转换或实现 Firebase 云消息传递正确处理传入消息所必需的onNewIntent

配置自定义入口点活动

如果您的应用程序不使用默认的UnityPlayerActivity ,您将需要删除提供的AndroidManifest.xml并确保您的自定义活动正确处理Android 活动生命周期的所有转换(如何执行此操作的示例如下所示)。如果您的自定义活动扩展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将为 null。

总之:

应用状态通知数据两个都
前景Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
背景系统托盘Firebase.Messaging.FirebaseMessaging.MessageReceived通知:系统托盘
数据:在意图的附加值中。

防止自动初始化

FCM 为设备定位生成一个注册令牌。生成令牌后,库会将标识符和配置数据上传到 Firebase。如果您想在使用令牌之前获得明确的选择加入,您可以通过禁用 FCM(以及在 Android 上的 Analytics)来防止在配置时生成。为此,请将元数据值添加到 Apple 上的Info.plist (不是GoogleService-Info.plist )或 Android 上的AndroidManifest.xml中:

安卓

<?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>

迅速

FirebaseMessagingAutoInitEnabled = NO

要重新启用 FCM,您可以进行运行时调用:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

一旦设置,此值将在应用重新启动时持续存在。

FCM 允许发送包含指向您的应用程序的深层链接的消息。要接收包含深层链接的消息,您必须向处理应用程序深层链接的活动添加一个新的意图过滤器。意图过滤器应该捕获您域的深层链接。如果您的消息不包含深层链接,则不需要此配置。在 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 发送下游消息和主题消息了。要了解更多信息,请参阅演示此功能的快速入门示例

要向您的应用添加其他更高级的行为,请参阅从应用服务器发送消息的指南:

请记住,您需要一个服务器实现才能使用这些功能。