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

要使用 Unity 编写您的跨平台 Firebase 云消息传递客户端应用,请使用 Firebase Cloud Messaging API。Unity SDK 在 Android 和 iOS 平台中都可使用,但需要针对每个平台进行一些额外设置。

开始之前

您必须先创建一个 Firebase 项目,并将 Firebase Unity SDK 软件包添加到您的 Unity 项目中,然后才能使用 Firebase 云消息传递

设置:

前提条件

Android

  • Unity 5.0 或更高版本
  • Android NDK 版本 10d 或更高版本

iOS

  • Unity 5.0 或更高版本
  • Xcode 8.0 或更高版本
  • 一台 iOS 真机
  • 已启用推送通知功能的 APNs 证书

如果您还没有 Unity 项目,可以下载我们的一个快速入门示例,试用一下特定的 Firebase 功能。如果使用快速入门示例,请不要忘记从项目设置中获取软件包标识符,下一步中会用到该标识符。

在 Firebase 控制台中设置您的应用

要将 Firebase 添加到您的应用,您需要有一个 Firebase 项目以及适用于您的应用的 Firebase 配置文件。

如果您还没有 Firebase 项目,请在 Firebase 控制台中创建一个。如果您已经有与自己的移动应用相关联的现有 Google 项目,请点击导入 Google 项目。如果没有,请点击添加项目

Android

  1. 点击将 Firebase 添加到您的 Android 应用,然后按设置步骤操作。如果您是导入现有 Google 项目,系统可能会自动执行这些操作,您只需下载配置文件即可。
  2. 当出现提示时,输入您的应用的软件包名称。请务必输入您的应用使用的软件包名称,因为您只有在向 Firebase 项目添加应用时,才能设置此名称。
  3. 按照说明下载 google-services.json 文件。您随时可以再重新下载此文件
  4. 将此文件复制到您项目的素材资源文件夹内的任意位置。

iOS

  1. 点击将 Firebase 添加到您的 iOS 应用,然后按设置步骤操作。如果您是导入现有 Google 项目,系统可能会自动执行这些操作,您只需下载配置文件即可。
  2. 当出现提示时,输入您的应用的软件包 ID。请务必输入您的应用使用的软件包 ID,因为您只有在向 Firebase 项目添加应用时,才能设置此 ID。
  3. 按照说明下载 GoogleService-Info.plist 文件。您随时可以再重新下载此文件
  4. GoogleService-Info.plist 文件添加到项目中。

  5. 将从 Firebase 控制台下载的 GoogleService-Info.plist 拖动到 Unity 项目中的任意文件夹内。

将 Firebase Unity SDK 添加到您的应用

  1. 下载 Firebase Unity SDK
  2. 依次选择 Assets > Import Package > Custom Package 菜单项。
  3. 从之前下载的 Firebase Unity SDK 中导入 FirebaseMessaging.unitypackage 软件包。
  4. 当出现 Import Unity Package 窗口时,点击 Import 按钮。

构建您的应用

Android

  1. 依次选择 File > Build Settings 菜单选项。
  2. 选择 Platform 列表中的 Android
  3. 点击 Switch Platform,选择 Android 作为目标平台。
  4. 等待 Unity 状态栏右下角的旋转进度条(正在编译)图标停止旋转。
  5. 点击 Build and Run

iOS

  1. 依次选择 File > Build Settings 菜单选项。
  2. 选择 Platform 列表中的 iOS
  3. 点击 Switch Platform,选择 iOS 作为目标平台。
  4. 等待 Unity 状态栏右下角的旋转进度条(正在编译)图标停止旋转。
  5. 点击 Build and Run

  6. Xcode 打开后,添加 UserNotifications.framework

    1. 点击 Xcode 中的项目,然后从 Editor 区域中选择 General 标签。
    2. 向下滚动到 Linked Frameworks and Libraries,然后点击 + 按钮添加框架。
    3. 在显示的窗口中,滚动到 UserNotifications.framework 并点击该条目,然后点击 Add

初始化 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 云消息传递附带了自定义入口点 Activity,用以替换默认的 UnityPlayerActivity。如果您使用的不是自定义入口点,则系统会自动进行此替换,无需您执行任何其他操作。不使用默认入口点 Activity 或提供自己的 Assets/Plugins/AndroidManifest.xml 的应用可能需要额外的配置。

Android 上的 Firebase 云消息传递 Unity 插件附带有两个附加文件:

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

提供这些文件是因为默认的 UnityPlayerActivity 不处理 onStoponRestart Activity 生命周期转换或者实现 onNewIntent,而后者对于 Firebase 云消息传递正确处理传入消息必不可缺。

配置自定义入口点 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
 * receieved 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());
  startService(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);
}

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

当应用根本没有运行而用户点按通知时,默认情况下,消息不会通过 FCM 的内置回调函数路由。在这种情况下,消息有效负载是通过用于启动应用的 Intent 接收的。

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

总结:

应用状态 通知 数据 两者
前台 Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
后台 系统任务栏 Firebase.Messaging.FirebaseMessaging.MessageReceived 通知:系统任务栏
数据:intent 的 extras 参数。

后续步骤

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

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

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

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面