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

如要使用 C++ 編寫跨平台 Firebase Cloud Messaging 用戶端應用程式，請使用 Firebase Cloud Messaging API。C++ SDK 適用於 Android 和 Apple 平台，但每個平台都需要額外設定。

設定 Firebase 和 FCM SDK

Android

1. 如果您尚未將 Firebase 新增至 C++ 專案，請先完成這項操作。

   • 在連結的設定操作說明中，查看裝置和應用程式使用 Firebase C++ SDK 的需求條件，包括使用 CMake 建構應用程式的建議。

   • 在專案層級的 build.gradle 檔案中，請務必在 buildscript 和 allprojects 區段中納入 Google 的 Maven 存放區。

   重要事項：請務必將 firebase_messaging 程式庫新增至 CMakeLists.txt 檔案。

2. 建立 Firebase App 物件，並傳入 JNI 環境和 Activity：

   app = ::firebase::App::Create(::firebase::AppOptions(), jni_env, activity);

3. 定義實作 firebase::messaging::Listener 介面的類別。

4. 初始化 FCM，傳入應用程式和建構的 Listener：

   ::firebase::messaging::Initialize(app, listener);

5. 依賴 Google Play 服務 SDK 的應用程式應先檢查裝置是否有相容的 Google Play 服務 APK，再存取相關功能。詳情請參閱「檢查 Google Play 服務 APK」。

iOS+

1. 如果您尚未將 Firebase 新增至 C++ 專案，請先新增。然後，為 FCM 設定專案：
   1. 在專案的 Podfile 中新增 FCM 依附元件：

      pod 'FirebaseMessaging'

   2. 將 firebase.framework 和 firebase_messaging.framework 架構從 Firebase C++ SDK 拖曳至 Xcode 專案。

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

   1. 在 Firebase 控制台的專案中，依序選取齒輪圖示、「Project Settings」(專案設定)，然後選取「Cloud Messaging」分頁。

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

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

3. 設定 Xcode 專案以啟用推播通知：

   1. 從導覽器區域選取專案。
   2. 從「Editor」區域選取專案目標。

   3. 選取「編輯器」區域中的「一般」分頁標籤。

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

      2. 在隨即顯示的視窗中，捲動至「User 通知.framework」，按一下該項目，然後按一下「Add」。

         這個架構僅會出現在 Xcode 8 以上版本中，且此程式庫需要這個架構。

   4. 在「編輯器」區域中選取「功能」分頁標籤。

      1. 將「推播通知」切換為「開啟」。
      2. 向下捲動至「背景模式」，然後將其切換為「開啟」。
      3. 選取「背景模式」下方的「遠端通知」。

4. 建立 Firebase App 物件：

   app = ::firebase::App::Create(::firebase::AppOptions());

5. 定義實作 firebase::messaging::Listener 介面的類別。

6. 初始化 Firebase 雲端通訊，傳入應用程式和建構的 Listener：

   ::firebase::messaging::Initialize(app, listener);

存取裝置註冊權杖

初始化 Firebase 雲端通訊程式庫後，系統會為用戶端應用程式執行個體要求註冊憑證。應用程式會透過 OnTokenReceived 回呼接收符記，該回呼應在實作 firebase::messaging::Listener 的類別中定義。

如果您要指定特定裝置，就必須取得這個權杖的存取權。

關於 Android 上的郵件傳送功能

如果應用程式未執行，且使用者輕觸通知，則根據預設，系統不會將訊息透過 FCM 內建的回呼重新導向。在這種情況下，系統會透過用於啟動應用程式的 Intent 接收訊息酬載。如要讓 FCM 將這些傳入的訊息轉送至 C++ 程式庫回呼，您必須覆寫活動中的 onNewIntent 方法，並將 Intent 傳遞至 MessageForwardingService。

import com.google.firebase.messaging.MessageForwardingService;

class MyActivity extends Activity {
  private static final String TAG = "MyActvity";

  @Override
  protected void onNewIntent(Intent intent) {
    Log.d(TAG, "A message was sent to this app while it was in the background.");
    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);
  }
}

應用程式在背景運作時收到的訊息具有通知欄位的內容，可用於填入系統匣通知，但不會將該通知內容傳達給 FCM。也就是說，Message::notification 會是空值。

簡單來說：

應用程式狀態	通知	資料	兩者並用
前景	OnMessageReceived	OnMessageReceived	OnMessageReceived
背景	系統匣	OnMessageReceived	通知：系統通知區 資料：意圖的額外資料。

在 Android 上處理自訂訊息

根據預設，傳送至應用程式的通知會傳遞至 ::firebase::messaging::Listener::OnMessageReceived，但在某些情況下，您可能需要覆寫預設行為。如要在 Android 上執行這項操作，您必須編寫可擴充 com.google.firebase.messaging.cpp.ListenerService 的自訂類別，並更新專案的 AndroidManifest.xml。

覆寫 ListenerService 方法。

ListenerService 是 Java 類別，可攔截傳送至應用程式的傳入訊息，並將訊息轉送至 C++ 程式庫。當應用程式處於前景 (或處於背景且接收僅限資料酬載) 時，訊息會透過此類別提供的其中一個回呼傳遞。如要在訊息處理中加入自訂行為，您必須擴充 FCM 的預設 ListenerService：

import com.google.firebase.messaging.cpp.ListenerService;

class MyListenerService extends ListenerService {

您可以覆寫 ListenerService.onMessageReceived 方法，根據收到的 RemoteMessage 物件執行動作，並取得訊息資料：

@Override
public void onMessageReceived(RemoteMessage message) {
  Log.d(TAG, "A message has been received.");
  // Do additional logic...
  super.onMessageReceived(message);
}

ListenerService 還有幾種較少使用的其他方法。這些值也可以覆寫，詳情請參閱 FirebaseMessagingService 參考資料。

@Override
public void onDeletedMessages() {
  Log.d(TAG, "Messages have been deleted on the server.");
  // Do additional logic...
  super.onDeletedMessages();
}

@Override
public void onMessageSent(String messageId) {
  Log.d(TAG, "An outgoing message has been sent.");
  // Do additional logic...
  super.onMessageSent(messageId);
}

@Override
public void onSendError(String messageId, Exception exception) {
  Log.d(TAG, "An outgoing message encountered an error.");
  // Do additional logic...
  super.onSendError(messageId, exception);
}

更新「AndroidManifest.xml」

自訂類別寫入後，必須包含在 AndroidManifest.xml 中才會生效。請在 <manifest> 標記中宣告適當的屬性，確保資訊清單包含合併工具，如下所示：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.google.firebase.messaging.cpp.samples"
    xmlns:tools="http://schemas.android.com/tools">

firebase_messaging_cpp.aar 封存檔中含有 AndroidManifest.xml 檔案，用於宣告 FCM 的預設 ListenerService。這個資訊清單通常會與專案專屬的資訊清單合併，後者是 ListenerService 能夠執行的方式。這個 ListenerService 需要替換為自訂的事件監聽器服務。方法是移除預設 ListenerService 並新增自訂服務，您可以透過專案 AndroidManifest.xml 檔案中的下列行程式碼來完成這項操作：

<service android:name="com.google.firebase.messaging.cpp.ListenerService"
         tools:node="remove" />

<service android:name="com.google.firebase.messaging.cpp.samples.MyListenerService"
         android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT"/>
  </intent-filter>
</service>

新版 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>

防止自動初始化

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::SetTokenRegistrationOnInitEnabled(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 傳送下游和主題訊息。詳情請參閱快速入門導覽課程範例中的這項功能，您可以下載、執行及查看。

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

• 傳送主題訊息
• 傳送至裝置群組

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