ไปที่คอนโซล

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

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

准备工作

第 1 步:设置环境

  • 安装 Unity 5.3 或更高版本。

  • (仅限 iOS)确保您已具备:

    • Xcode 9.4.1 或更高版本
    • CocoaPods 1.4.0 或更高版本
  • 确保您的 Unity 项目以适当的操作系统级别为目标:

    • 对于 iOS - 目标为 iOS 8 或更高版本
    • 对于 Android - 目标为 API 级别 16 (Jelly Bean) 或更高版本
  • 设置可用于运行 Unity 项目的设备或模拟器。

    • 对于 iOS - 为了支持 Firebase 云消息传递,您需要:

      • 一台 iOS 真机
      • 已启用推送通知功能的 APNs 证书
    • 对于 Android - 模拟器必须使用 Google Play 提供的模拟器映像。

  • 使用您的 Google 帐号登录 Firebase

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

第 2 步:创建 Firebase 项目

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

第 3 步:在 Firebase 中注册 Unity 项目

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

  1. Firebase 控制台的项目概览页面的中心位置,点击 Unity 图标以启动设置工作流。

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

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

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

    1. 在 Unity IDE 中打开您的 Unity 项目。

    2. 依次转到 Build Settings > iOSAndroid > Player Settings > Other Settings

      Unity 项目的 ID 是软件包标识符的值。(ID 示例:com.yourcompany.unity-project-name

    3. 在相应字段中输入每个针对具体平台的 ID:

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

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

        • 术语“软件包名称”和“应用 ID”通常可互换使用。
  4. (可选)输入 Unity 项目针对具体平台的别名。

    这些别名是方便内部使用的标识符,只有您能在 Firebase 控制台中看到。

  5. 点击注册应用

第 4 步:将 Firebase 配置文件添加至 Unity 项目中

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

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

    • 在移动配置文件之前,请确保配置文件名未附加其他字符,例如 (2)
    • 您可以将 Firebase 配置文件保存在 Assets 文件夹中的任意位置。
  3. 返回 Firebase 控制台,在设置工作流中,点击下一步

第 5 步:将 Firebase SDK 添加至 Unity 项目

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

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

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

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

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

    为了获得最佳的 Firebase 云消息传递使用体验,我们建议您在项目中启用 Google Analytics(分析)。在设置 Google Analytics(分析)的过程中,您需要将支持 Google Analytics(分析)的 Firebase 软件包添加到应用中。

    已启用 Analytics

    • 添加支持 Google Analytics(分析)的 Firebase 软件包:FirebaseAnalytics.unitypackage
    • 添加 Firebase 云消息传递软件包:FirebaseMessaging.unitypackage

    未启用 Analytics

    添加 Firebase 云消息传递软件包:FirebaseMessaging.unitypackage

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

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

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

Android 版 Firebase Unity SDK 需要使用 Google Play 服务。您必须先将 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 中的项目,然后从 Editor area 中选择 General 标签页。

  2. 向下滚动到 Linked Frameworks and Libraries,然后点击 + 号按钮以添加框架。

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

第 8 步:启用推送通知

  1. 点击 Xcode 中的项目,然后从 Editor area 中选择 Capabilities 标签页。

  2. Push Notifications 切换为 On

  3. 向下滚动到 Background Modes,然后将其切换为 On

  4. Background Modes 下选择 Remote notifications 复选框。

初始化 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
 * 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());
  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 参数。

防止自动初始化

FCM 会生成一个实例 ID,并在 FCM 中将其用作注册令牌。在生成实例 ID 后,库会将标识符和配置数据上传到 Firebase。如果您想在使用实例 ID 之前能够明确地自行选择,则可以通过在配置时停用 FCM(如果是 Android,则还要停用 Analytics)来防止生成该 ID。为此,请向 iOS 上的 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>

iOS

FirebaseMessagingAutoInitEnabled = NO

如需重新启用 FCM,您可以执行运行时调用:

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

此值一经设置,就会在应用重启后持久保存。

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 发送下行消息和主题消息。如需了解详情,请参阅对此功能进行了演示的快速入门示例

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

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