使用 Unity 設定 Firebase 雲端通訊用戶端應用程式

如要使用 Unity 編寫跨平台 Firebase Cloud Messaging 用戶端應用程式,請使用 Firebase Cloud Messaging API。 Unity SDK 適用於 Android 和 Apple,但需要進行額外設定 各個平台。

事前準備

事前準備

  • 安裝 Unity 2021 LTS 以上版本。支援 Unity 2020 ,且會在下一個重大事件發生後不再受到支援 版本。這個版本也可能相容,但日後不會再運作 支援。

  • (僅限 Apple 平台) 安裝以下項目:

    • Xcode 13.3.1 以上版本
    • CocoaPods 1.12.0 以上版本
  • 請確認您的 Unity 專案符合下列規定:

    • iOS - 指定 iOS 13 以上版本
    • 針對 tvOS:指定 tvOS 13 以上版本
    • Android - 指定 API 級別 19 (KitKat) 以上版本
  • 設定裝置或使用模擬器執行 Unity 專案。

    • iOS 或 tvOS:設定實體裝置來執行 ,然後完成以下工作:

    • Android 裝置模擬器必須使用 模擬器映像檔。

如果您還沒有 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 ] 欄位。

    • Android:在網站的 Android 套件 name (名稱) 欄位輸入新的名稱。
      經常使用「套件名稱」和「應用程式 ID」這兩個字詞 兩地間的關聯

    ,瞭解如何調查及移除這項存取權。
  5. (選用) 輸入 Unity 專案的平台專屬暱稱。
    這些暱稱為內部方便識別身分,且只有公開顯示 是在 Firebase 控制台中確定。

  6. 按一下 [Register app] (註冊應用程式)

步驟 3:新增 Firebase 設定檔

  1. 取得特定平台的 Firebase 設定檔,方法是前往 Firebase 控制台設定工作流程。

    • iOS 裝置 — 點選「Download GoogleService-Info.plist」

    • Android 裝置 - 點選「Download google-services.json」

  2. 開啟 Unity 專案的「Project」視窗,然後移動設定 檔案複製到 Assets 資料夾中。

  3. 返回 Firebase 控制台,在設定工作流程中點選「下一步」

步驟 4:新增 Firebase Unity SDK

  1. Firebase 控制台中,依序按一下「Download Firebase Unity SDK」和解壓縮 下載 SDK

    • 您隨時可以再次下載 Firebase Unity SDK

    • Firebase Unity SDK 不限於特定平台。

  2. 在開啟的 Unity 專案中,前往 素材資源 >「Import Package」>自訂套件

  3. 在已解壓縮的 SDK 中,選取系統支援的 Firebase 裝置 要使用的產品

    為透過 Firebase Cloud Messaging 獲得最佳體驗,建議你 正在啟用 Google Analytics 資源數量此外,設定 Analytics 時,您需要新增 將 Analytics 的 Firebase 套件套用至您的應用程式。

    已啟用 Analytics

    • 新增 Google Analytics 的 Firebase 套件: FirebaseAnalytics.unitypackage
    • 新增 Firebase Cloud Messaging 的套件: FirebaseMessaging.unitypackage

    未啟用「Analytics

    新增 Firebase Cloud Messaging 的套件: FirebaseMessaging.unitypackage

  4. 在「Import Unity Package」視窗中,按一下「Import」

  5. 返回 Firebase 控制台,在設定工作流程中點選「下一步」

步驟 5:確認 Google Play 服務版本規定

Firebase Unity SDK for Android 規定 Google Play services,其中必須 但 SDK 必須是最新版本 才能使用 SDK

將下列 using 陳述式和初始化程式碼加到 應用程式。您可以檢查 Google Play services,並視需要更新 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 支援的 APN 驗證金鑰

將 APN 驗證金鑰上傳至 Firebase。 如果您還沒有 APN 驗證金鑰,請務必前往 Apple Developer Member Center

  1. Firebase 控制台的專案中,選取 齒輪圖示,選取 「Project Settings」,然後選取 「雲端通訊」分頁。

  2. 在「iOS 應用程式設定」下方的「APNs 驗證金鑰」中, 按一下「上傳」圖示 按鈕。

  3. 瀏覽至儲存金鑰的位置並選取金鑰,然後按一下 開啟。加入金鑰的金鑰 ID (位於 Apple Developer Member Center 時,按一下 按一下「上傳」

啟用 Apple 平台上的推播通知

步驟 1:新增使用者通知架構

  1. 點選 Xcode 中的專案,然後選取「General」分頁標籤 編輯器區域

  2. 向下捲動到「Linked Framework and Libraries」,然後按一下「+」。 按鈕來新增架構

  3. 在隨即顯示的視窗中,捲動至「User 通知.framework」,然後按一下,然後點選 然後按一下「新增」

步驟 2:啟用推播通知

  1. 按一下 Xcode 中的專案,然後選取「Capabilities」(功能) 分頁標籤 編輯器區域

  2. 將「推播通知」切換為「開啟」

  3. 向下捲動至「背景模式」,然後將設定切換為「開啟」

  4. 在「背景模式」下方,勾選「遠端通知」核取方塊。

初始化 Firebase Cloud Messaging

新增處理常式時,系統會初始化 Firebase Cloud Message 程式庫 TokenReceivedMessageReceived 事件。

初始化時,用戶端應用程式要求一個註冊符記 執行個體。應用程式會收到含有 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 進入點活動

在 Android 裝置上,Firebase Cloud Messaging 隨附自訂進入點 取代預設 UnityPlayerActivity 的活動如果不是使用 這個替代動作會自動發生 必須採取其他行動未使用預設進入點的應用程式 需要自行提供 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 處理傳入的訊息。

設定自訂進入點活動

如果您的應用程式未使用預設的 UnityPlayerActivity,您需要 移除提供的 AndroidManifest.xml,並確保您的自訂活動 能正確地處理 Android 活動生命週期 (範例如下)。如果您的 活動延長 UnityPlayerActivity,可以改為擴充 com.google.firebase.MessagingUnityPlayerActivity實作所有 一些必要的方法

如果您使用的是自訂 Activity,且沒有 com.google.firebase.MessagingUnityPlayerActivity,您應該加入 程式碼片段。

/**
 * 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 以上版本) 會使用 JobIntentServiceAndroidManifest.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 為空值。

簡單來說:

應用程式狀態 通知 資料 兩者並用
前景 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

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>

Swift

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 管理訊息。詳情請參閱 快速入門導覽課程範例 用於展示這項功能

如要為應用程式新增其他進階行為,請參閱傳送指南 訊息:

請注意,你必須在 伺服器導入,以使用 接著介紹網際網路通訊層 包括兩項主要的安全防護功能