如要使用 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 使用模擬器映像檔。
- 使用 Google 帳戶登入 Firebase。
如果您還沒有 Unity 專案,只是想試用 Firebase 產品,可以下載其中一個快速入門導覽課程範例。
步驟 1:建立 Firebase 專案
您必須先建立要連結至 Unity 專案的 Firebase 專案,才能將 Firebase 新增到 Unity 專案。如要進一步瞭解 Firebase 專案,請參閱「瞭解 Firebase 專案」。
步驟 2:向 Firebase 註冊應用程式
您可以註冊一或多個應用程式或遊戲,以便與 Firebase 專案連結。
前往 Firebase 主控台。
在專案總覽頁面中間的「Unity」圖示 (
) 啟動設定工作流程。如果您已經在 Firebase 專案中加入應用程式,請按一下「Add app」顯示平台選項。
選取您要註冊的 Unity 專案的建構目標,或選擇立即註冊兩個目標。
輸入 Unity 專案的平台專屬 ID。
iOS:在「iOS 軟體包 ID」欄位中輸入 Unity 專案的 iOS 編號。
Android:在「Android package name」(Android 套件名稱) 欄位中輸入 Unity 專案的 Android ID。
套件名稱和應用程式 ID 這兩個字詞經常會交替使用。
(選用) 輸入 Unity 專案的平台專屬暱稱。
這些暱稱是內部便利 ID,只有您可在 Firebase 控制台中看到。按一下 [Register app] (註冊應用程式)。
步驟 3:新增 Firebase 設定檔
在 Firebase 主控台設定工作流程中,取得平台專屬的 Firebase 設定檔。
iOS 裝置 — 點選「Download GoogleService-Info.plist」。
Android 裝置 - 點選「Download google-services.json」。
開啟 Unity 專案的「Project」視窗,然後將設定檔移至
Assets
資料夾。返回 Firebase 控制台,在設定工作流程中點選「下一步」。
步驟 4:新增 Firebase Unity SDK
在 Firebase 控制台中,按一下「Download Firebase Unity SDK」,然後將 SDK 解壓縮。
您隨時可以再次下載 Firebase Unity SDK。
Firebase Unity SDK 並非平台專用。
在開放式 Unity 專案中,依序前往「Assets」 >「Import Package」 >「Custom Package」。
在已解壓縮的 SDK 中,選取要在應用程式中使用支援的 Firebase 產品。
為獲得最佳 Firebase 雲端通訊體驗,建議您在專案中啟用 Google Analytics (分析)。此外,在設定 Analytics (分析) 的過程中,您必須將 Analytics (分析) 的 Firebase 套件新增至應用程式。
Analytics (分析) 已啟用
- 新增 Google Analytics (分析) 專用 Firebase 套件:
FirebaseAnalytics.unitypackage
- 新增 Firebase 雲端通訊套件:
FirebaseMessaging.unitypackage
未啟用 Analytics (分析)
新增 Firebase 雲端通訊套件:
FirebaseMessaging.unitypackage
- 新增 Google Analytics (分析) 專用 Firebase 套件:
在「Import Unity Package」視窗中,按一下「Import」。
返回 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 平台上的推播通知
步驟 1:新增使用者通知架構
按一下 Xcode 中的專案,然後從「Editor」區域選取「General」分頁標籤。
向下捲動至「Linked Framework and Libraries」,然後按一下「+」按鈕新增架構。
在隨即顯示的視窗中,捲動至「UserNotification.framework」,按一下該項目,然後按一下「Add」。
步驟 2:啟用推播通知
按一下 Xcode 中的專案,然後從「Editor」區域選取「Capabilities」分頁標籤。
將「推播通知」切換為「開啟」。
向下捲動至「背景模式」,然後將設定切換為「開啟」。
在「背景模式」下方,勾選「遠端通知」核取方塊。
初始化 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 進入點活動
在 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
不會處理onStop
、onRestart
活動生命週期轉換,或是實作 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;
設定這個值後,每次重新啟動的應用程式都會保留這個值。
在 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 傳送下游和主題訊息了。詳情請參閱示範此功能的快速入門導覽課程範例。
如要為應用程式新增其他進階行為,請參閱從應用程式伺服器傳送訊息的指南:
請注意,您需要伺服器實作才能使用這些功能。