使用 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.12.0 或更高版本
  • 確保您的 Unity 專案符合以下要求:

    • 對於 iOS — 面向 iOS 11 或更高版本
    • 對於 tvOS - 目標為 tvOS 12 或更高版本
    • 對於 Android — 目標 API 等級 19 (KitKat) 或更高版本
  • 設定設備或使用模擬器來運行您的 Unity 專案。

    • 對於 iOS 或 tvOS — 設定實體裝置來運行您的應用程序,並完成以下任務:

      • 為您的Apple 開發者帳戶取得 Apple 推播通知驗證金鑰。
      • App > Capability下的 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 控制台中,按一下「下載 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。

在應用程式的開頭加入以下using語句和初始化程式碼。在呼叫 SDK 中的任何其他方法之前,您可以檢查 Google Play 服務並將其更新為 Firebase Unity SDK 所需的版本。

using Firebase.Extensions;
Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(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 雲端訊息傳遞

TokenReceivedMessageReceived事件新增處理程序時,將初始化 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不處理onStoponRestart活動生命週期轉換或實作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。

總之:

應用程式狀態通知數據兩個都
前景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-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 發送下游訊息和主題訊息。要了解更多信息,請參閱演示此功能的快速入門範例

若要為您的應用程式新增其他更進階的行為,請參閱從應用程式伺服器傳送訊息的指南:

請記住,您需要一個伺服器實作才能使用這些功能。