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

如要使用 Unity 編寫跨平台 Firebase 雲端通訊用戶端應用程式,請使用 Firebase 雲端通訊 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」 >「Capabilities」,在 XCode 中啟用推播通知。
    • Android模擬器必須搭配 Google Play 使用模擬器映像檔。

如果您還沒有 Unity 專案,只是想試用 Firebase 產品,可以下載其中一個快速入門導覽課程範例

步驟 1:建立 Firebase 專案

您必須先建立要連結至 Unity 專案的 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 package name」(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 雲端通訊體驗,建議您在專案中啟用 Google Analytics (分析)。此外,在設定 Analytics (分析) 的過程中,您必須將 Analytics (分析) 的 Firebase 套件新增至應用程式。

    Analytics (分析) 已啟用

    • 新增 Google Analytics (分析) 專用 Firebase 套件: FirebaseAnalytics.unitypackage
    • 新增 Firebase 雲端通訊套件:FirebaseMessaging.unitypackage

    未啟用 Analytics (分析)

    新增 Firebase 雲端通訊套件:FirebaseMessaging.unitypackage

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

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

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

Android 版 Firebase Unity SDK 需要 Google Play 服務,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 支援的 APN 驗證金鑰

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

  1. 在 Firebase 控制台的專案中,依序選取齒輪圖示 >「專案設定」,然後選取「雲端通訊」分頁標籤。

  2. 在「iOS app configuration」下方的「APNs 驗證金鑰」中,按一下「上傳」按鈕。

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

啟用 Apple 平台上的推播通知

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

  1. 按一下 Xcode 中的專案,然後從「Editor」區域選取「General」分頁標籤。

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

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

步驟 2:啟用推播通知

  1. 按一下 Xcode 中的專案,然後從「Editor」區域選取「Capabilities」分頁標籤。

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

在 Android 中,Firebase 雲端通訊提供自訂進入點活動,取代預設的 UnityPlayerActivity。如果您並未使用自訂進入點,此替換作業會自動進行,因此您無需採取任何其他動作。如果應用程式未使用預設進入點活動,或是自行提供 Assets/Plugins/AndroidManifest.xml,就需要額外設定。

Android 上的 Firebase 雲端通訊 Unity 外掛程式隨附以下兩個檔案:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar 包含名為 MessagingUnityPlayerActivity 的活動,用於取代標準 UnityPlayerActivity
  • Assets/Plugins/Android/AndroidManifest.xml 會指示應用程式使用 MessagingUnityPlayerActivity 做為應用程式的進入點。

之所以提供這些檔案,是因為預設的 UnityPlayerActivity 不會處理onStoponRestart活動生命週期轉換,或是實作 onNewIntent Firebase 雲端通訊正確處理傳入訊息所需的資訊。

設定自訂進入點活動

如果應用程式未使用預設的 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 傳送下游和主題訊息了。詳情請參閱示範此功能的快速入門導覽課程範例

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

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