Catch up on highlights from Firebase at Google I/O 2023. Learn more

使用 Unity 設置 Firebase 雲消息傳遞客戶端應用

要使用 Unity 編寫跨平台 Firebase 雲消息傳遞客戶端應用程序，請使用Firebase 雲消息傳遞API。 Unity SDK 適用於 Android 和 Apple，每個平台都需要一些額外的設置。

在你開始之前

先決條件

  • 安裝 Unity 2019.1 或更高版本。早期版本也可能兼容，但不會得到積極支持。對 Unity 2019.1 的支持被視為已棄用，下一個主要版本後將不再提供積極支持。

  • （僅限 Apple 平台）安裝以下內容：

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

  • 確保您的 Unity 項目滿足以下要求：

    • 對於 iOS — 針對 iOS 11 或更高版本
    • 對於 tvOS - 針對 tvOS 12 或更高版本
    • 對於 Android——目標 API 級別 19 (KitKat) 或更高

  • 設置設備或使用模擬器來運行您的 Unity 項目。

    • 對於 iOS 或 tvOS — 設置物理設備來運行您的應用程序，並完成以下任務：

      • 為您的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。

在 Apple 平台上啟用推送通知

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

  1. 單擊 Xcode 中的項目，然後從編輯器區域選擇常規選項卡。

  2. 向下滾動到Linked Frameworks and Libraries ，然後單擊+按鈕添加一個框架。

  3. 在出現的窗口中，滾動到UserNotifications.framework ，單擊該條目，然後單擊Add 。

第 2 步：啟用推送通知

  1. 單擊 Xcode 中的項目，然後從Editor 區域中選擇Capabilities選項卡。

  2. 將推送通知切換為開。

  3. 向下滾動到“背景模式” ，然後將其切換到“開” 。

  4. 選擇背景模式下的遠程通知複選框。

初始化 Firebase 雲消息傳遞

在為TokenReceived或MessageReceived事件添加處理程序時，將初始化 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不處理onStop 、 onRestart活動生命週期轉換或實現 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 發送下游消息和主題消息了。要了解更多信息，請參閱演示此功能的快速入門示例。

要向您的應用添加其他更高級的行為，請參閱從應用服務器發送消息的指南：

請記住，您需要一個服務器實現才能使用這些功能。