使用 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 應用程式物件，並傳遞 JNI 環境和活動：

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

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

4. 初始化 FCM，並傳遞應用程式和建構的接聽程式：

   ::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。 如果沒有 APNs 驗證金鑰，請務必在 Apple 開發人員會員中心建立。

   1. 在 Firebase 控制台的專案中，依序選取齒輪圖示、「專案設定」和「Cloud Messaging」分頁標籤。

   2. 在「iOS 應用程式設定」下方的「APN 驗證金鑰」中， 按一下「上傳」按鈕，上傳開發或正式版驗證金鑰，或同時上傳兩者。至少必須有一個。

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

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

   1. 從「Navigator area」選取專案。
   2. 從編輯器區域選取專案目標。

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

      1. 向下捲動至「Linked Frameworks and Libraries」(連結的架構和程式庫)，然後點選「+」按鈕新增架構。

      2. 在顯示的視窗中，捲動至「UserNotifications.framework」，點選該項目，然後按一下「Add」。

         這個架構只會顯示在 Xcode 第 8 版以上，且是這個程式庫的必要架構。

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

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

4. 建立 Firebase 應用程式物件：

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

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

6. 初始化 Firebase 雲端通訊，並傳遞應用程式和建構的接聽程式：

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

存取裝置註冊權杖

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

如要指定該裝置，您必須取得這個權杖。

Android 裝置上的訊息傳送注意事項

如果應用程式完全沒有執行，且使用者輕觸通知，根據預設，訊息不會透過 FCM 的內建回呼路徑傳送。在這種情況下，系統會透過Intent接收訊息酬載，如要讓 FCM 將這些傳入訊息轉送至 C++ 程式庫回呼，您需要在 Activity 中覆寫 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 傳送下游訊息和主題訊息。如要瞭解詳情，請參閱快速入門範例，下載、執行並查看這項功能。

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

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

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