使用 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 級別 21 (Lollipop) 以上版本
  • 設定裝置或使用模擬器執行 Unity 專案。

    • 適用於 iOS 或 tvOS:設定實體裝置來執行應用程式,並完成下列工作:

      • 取得 Apple Developer 帳戶的 Apple 推播通知驗證金鑰。
      • 在 XCode 中依序前往「App」>「Capabilities」,啟用推播通知。
    • Android 適用模擬器必須使用含有 Google Play 的模擬器映像檔。

如果您尚未擁有 Unity 專案,但想試用 Firebase 產品,可以下載我們的快速入門範例

步驟 1:建立 Firebase 專案

您必須先建立 Firebase 專案,才能將 Firebase 新增至 Unity 專案。請參閱「瞭解 Firebase 專案」一文,進一步瞭解 Firebase 專案。

步驟 2:透過 Firebase 註冊應用程式

您可以註冊一或多個應用程式或遊戲,以便連結至 Firebase 專案。

  1. 前往 Firebase 控制台

  2. 在專案總覽頁面中間的「Unity」圖示 () 啟動設定工作流程。

    如果您已經在 Firebase 專案中加入應用程式,請按一下「Add app」顯示平台選項。

  3. 選取要註冊的 Unity 專案版本目標,甚至可以同時選取註冊兩個目標。

  4. 輸入 Unity 專案的平台專屬 ID。

    • iOS:在「iOS 軟體包 ID欄位中輸入 Unity 專案的 iOS 編號。

    • 適用於 Android:在「Android 套件名稱欄位中輸入 Unity 專案的 Android ID。
      「套件名稱」和「應用程式 ID」這兩個詞彙經常互通使用。

  5. (選用) 輸入 Unity 專案的平台專屬暱稱。
    這些別名是內部方便使用的 ID,只有您在 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 專案中,依序前往「Assets」>「Import Package」>「Custom 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 服務版本規定

Android 版 Firebase Unity SDK 需要 Google Play services,而這個 SDK 必須是最新版本才能使用 SDK。

在應用程式啟動時,加入下列 using 陳述式和初始化程式碼。在呼叫 SDK 中的任何其他方法之前,您可以先檢查 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。

上傳 APNs 驗證金鑰,以便 Apple 支援團隊提供協助

將 APNs 驗證金鑰上傳至 Firebase。如果您尚未取得 APNs 驗證金鑰,請務必前往 Apple Developer Member Center 建立金鑰。

  1. Firebase 控制台的專案中選取齒輪圖示,然後依序選取「Project Settings」和「Cloud Messaging」分頁標籤。

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

  3. 瀏覽至儲存金鑰的位置,選取金鑰,然後按一下「Open」。加入金鑰金鑰 ID (可於 Apple Developer Member Center 中找到),然後按一下「上傳」

在 Apple 平台上啟用推播通知

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

  1. 在 Xcode 中按一下專案,然後在「編輯器」區域中選取「一般」分頁。

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

  3. 在隨即顯示的視窗中,捲動至「UserNotifications.framework」,按一下該項目,然後按一下「Add」

步驟 2:啟用推播通知

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

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

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

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

初始化 Firebase Cloud Messaging

新增 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 進入點活動

在 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 無法處理 onStoponRestart 活動生命週期轉換,或實作 onNewIntent,而這對 Firebase Cloud Messaging 正確處理傳入訊息而言,是必要的。

設定自訂進入點活動

如果您的應用程式未使用預設 UnityPlayerActivity,您必須移除提供的 AndroidManifest.xml,並確保自訂活動能正確處理 Android 活動生命週期的所有轉換 (如需瞭解如何執行此操作,請參閱下方的範例)。如果自訂活動擴充 UnityPlayerActivity,您可以改為擴充 com.google.firebase.MessagingUnityPlayerActivity,藉此實作所有必要方法。

如果您使用的是自訂活動,且未擴充 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 以上版本) 會使用 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 會是空值。

簡單來說:

應用程式狀態 通知 資料 兩者並用
前景 Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
背景 系統匣 Firebase.Messaging.FirebaseMessaging.MessageReceived 通知:系統匣
資料:意圖的額外項目。

防止自動初始化

FCM 會為裝置指定目標產生註冊權杖。產生權杖後,程式庫會將 ID 和設定資料上傳至 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 傳送下游和主題訊息。如需更多資訊,請參閱快速入門範例,瞭解這項功能。

如要為應用程式新增其他進階行為,請參閱以下指南,瞭解如何透過應用程式伺服器傳送訊息:

請注意,您需要伺服器實作才能使用這些功能。