使用 Unity 設置 Firebase 雲消息傳遞客戶端應用

要使用 Unity 編寫跨平台 Firebase Cloud Messaging 客戶端應用程序,請使用Firebase Cloud Messaging API。 Unity SDK 適用於 Android 和 Apple,每個平台都需要一些額外的設置。

在你開始之前

先決條件

  • 安裝 Unity 2018.4 或更高版本。早期版本也可能兼容,但不會受到積極支持。對 Unity 2018.4 的支持被視為已棄用,在下一個主要版本之後將不再積極支持。

  • (僅限 iOS)安裝以下內容:

    • Xcode 13.3.1 或更高版本
    • CocoaPods 1.10.0 或更高版本
  • 確保您的 Unity 項目滿足以下要求:

    • 對於 iOS - 針對 iOS 10 或更高版本
    • 對於 Android - 目標 API 級別 19 (KitKat) 或更高

  • 設置設備或使用模擬器來運行您的 Unity 項目。

    • 對於 iOS - 設置物理 iOS 設備來運行您的應用程序,並完成以下任務:

      • 為您的Apple Developer 帳戶獲取 Apple Push Notification Authentication Key。
      • 在 XCode 中的App > Capabilities下啟用推送通知。
    • 對於 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 項目的Project窗口,然後將配置文件移動到Assets文件夾中。

  3. 返回 Firebase 控制台,在設置工作流程中,單擊Next

第 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 包添加到您的應用中。

    啟用分析

    • 為 Google Analytics 添加 Firebase 包: FirebaseAnalytics.unitypackage
    • 為 Firebase Cloud Messaging 添加包: FirebaseMessaging.unitypackage

    未啟用分析

    為 Firebase Cloud Messaging 添加包: FirebaseMessaging.unitypackage

  4. 在“導入 Unity 包”窗口中,單擊“導入”。

  5. 返回 Firebase 控制台,在設置工作流程中,單擊Next

第 5 步:確認 Google Play 服務版本要求

適用於 Android 的 Firebase Unity SDK 需要Google Play 服務,該服務必須是最新的,才能使用 SDK。

在應用程序的開頭添加以下代碼。在調用 SDK 中的任何其他方法之前,您可以檢查並選擇將 Google Play 服務更新到 Firebase Unity SDK 所需的版本。

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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。

第 7 步:添加用戶通知框架

  1. 單擊 Xcode 中的項目,然後從Editor area中選擇General選項卡。

  2. 向下滾動到Linked Frameworks and Libraries ,然後單擊+按鈕添加框架。

  3. 在出現的窗口中,滾動到UserNotifications.framework ,單擊該條目,然後單擊Add

第 8 步:啟用推送通知

  1. 單擊 Xcode 中的項目,然後從Editor area中選擇Capabilities選項卡。

  2. 將推送通知切換到O ​​n 。

  3. 向下滾動到Background Modes ,然後將其切換到O ​​n 。

  4. 選中後台模式下的遠程通知複選框。

初始化 Firebase 雲消息傳遞

在為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 入口點 Activity

在 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活動生命週期轉換或實現 Firebase 雲消息傳遞正確處理傳入消息所必需的onNewIntent

配置自定義入口點 Activity

如果您的應用程序不使用默認的UnityPlayerActivity ,您將需要刪除提供的AndroidManifest.xml並確保您的自定義活動正確處理Android 活動生命週期的所有轉換(如何執行此操作的示例如下所示)。如果您的自定義活動擴展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將為空。

總之:

應用狀態通知數據兩個都
前景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>

當用戶點擊包含指向您指定的方案和主機的鏈接的通知時,您的應用將使用此意圖過濾器啟動 Activity 以處理該鏈接。

下一步

設置客戶端應用程序後,您就可以使用 Firebase 發送下游和主題消息了。要了解更多信息,請參閱演示此功能的快速入門示例

要向您的應用添加其他更高級的行為,請參閱從應用服務器發送消息的指南:

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