使用 Unity 設定 Firebase Cloud Messaging 用戶端應用

要使用 Unity 編寫跨平台 Firebase Cloud Messaging 客戶端應用，請使用Firebase Cloud Messaging 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 開發者帳戶獲取 Apple 推送通知身份驗證密鑰。
    • 在App > Capability下的 XCode 中啟用推送通知。

  • 對於 Android —模擬器必須使用 Google Play 模擬器映像。

• 使用您的 Google 帳戶登錄 Firebase 。

如果您還沒有 Unity 項目而只想嘗試 Firebase 產品，則可以下載我們的快速入門示例之一。

第 1 步：創建 Firebase 項目

在將 Firebase 添加到 Unity 項目之前，您需要創建一個 Firebase 項目以連接到您的 Unity 項目。訪問了解 Firebase 項目以了解有關 Firebase 項目的更多信息。

第 2 步：向 Firebase 註冊您的應用

您可以註冊一個或多個應用或遊戲來與您的 Firebase 項目連接。

1. 轉到Firebase 控制台。

2. 在項目概述頁面的中心，單擊Unity圖標 ( plat_unity ) 以啟動設置工作流程。

   如果您已將應用添加到 Firebase 項目，請單擊添加應用以顯示平台選項。

3. 選擇您想要註冊的 Unity 項目的構建目標，或者您甚至可以選擇現在同時註冊兩個目標。

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 ）。

5. （可選）輸入 Unity 項目的平台特定暱稱。
   這些暱稱是內部方便標識符，僅您在 Firebase 控制台中可見。

6. 單擊註冊應用程序。

第 3 步：添加 Firebase 配置文件

1. 在 Firebase 控制台設置工作流程中獲取特定於平台的 Firebase 配置文件。

   • 對於 iOS — 單擊下載 GoogleService-Info.plist 。

   • 對於 Android — 單擊下載 google-services.json 。

   關於這個配置文件您需要了解什麼？

   • Firebase 配置文件包含您的項目的唯一但非秘密的標識符。要了解有關此配置文件的更多信息，請訪問了解 Firebase 項目。

   • 您可以隨時再次下載Firebase 配置文件。

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

2. 打開 Unity 項目的項目窗口，然後將配置文件移至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 包添加到您的應用中。

   啟用分析

   • 添加適用於 Google Analytics 的 Firebase 包： FirebaseAnalytics.unitypackage
   • 添加 Firebase 雲消息傳遞包： FirebaseMessaging.unitypackage

   未啟用分析

   添加 Firebase 雲消息傳遞包： 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. 向下滾動到鏈接的框架和庫，然後單擊+按鈕添加框架。

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

第 2 步：啟用推送通知

1. 單擊 Xcode 中的項目，然後從編輯器區域選擇“功能”選項卡。

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

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

4. 選擇“後台模式”下的“遠程通知”複選框。

初始化 Firebase 雲消息傳遞

為TokenReceived或MessageReceived事件添加處理程序時，將初始化 Firebase Cloud Message 庫。

初始化時，會請求客戶端應用程序實例的註冊令牌。應用程序將通過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，該 Activity 取代了默認的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活動生命週期轉換或實現onNewIntent （這是 Firebase Cloud Messaging 正確處理傳入消息所必需的）。

配置自定義入口點 Activity

如果您的應用程序不使用默認的UnityPlayerActivity ，您將需要刪除提供的AndroidManifest.xml並確保您的自定義活動正確處理Android 活動生命週期的所有轉換（下面顯示瞭如何執行此操作的示例）。如果您的自定義 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將為 null。

總之：

防止自動初始化

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;

設置後，該值將在應用程序重新啟動後保持不變。

在 Android 上處理帶有深層鏈接的消息

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

當用戶點擊包含指向您指定的方案和主機的鏈接的通知時，您的應用程序將使用此意圖過濾器啟動活動來處理該鏈接。

下一步

設置客戶端應用程序後，您就可以使用 Firebase 發送下游消息和主題消息。要了解更多信息，請參閱演示此功能的快速入門示例。

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

• 發送主題消息
• 發送到設備組
• 發送上游消息

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