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

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

設定 Firebase 和 FCM SDK

Android

1. 如果您尚未將 Firebase 新增至 C++ 專案，請將 Firebase 新增至 C++ 專案。

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

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

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

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

   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 C++ SDK 將 firebase.framework 和 firebase_messaging.framework 架構拖曳至 Xcode 專案。

2. 將 APNs 驗證金鑰上傳至 Firebase。如果您尚未取得 APNs 驗證金鑰，請務必前往 Apple Developer Member Center 建立金鑰。

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

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

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

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

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

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

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

      2. 在隨即顯示的視窗中，捲動至「UserNotifications.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 傳送下游和主題訊息。如需更多資訊，請參閱快速入門範例中展示的這項功能，您可以下載、執行及查看這項功能。

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

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

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