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

如要使用 C++ 編寫跨平台 Firebase 雲端通訊用戶端應用程式,請使用 Firebase 雲端通訊 API。C++ SDK 適用於 Android 和 Apple 平台,但每個平台都需要進行一些額外設定。

設定 Firebase 和 FCM SDK

Android

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

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

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

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

    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. 您需要有效的 APN 憑證。如果您還沒有帳戶,請務必前往 Apple Developer Member Center 建立。
  2. 如果您尚未將 Firebase 新增至 C++ 專案,請先完成這項操作。然後為 FCM 設定專案:
    1. 在專案的 Podfile 中新增 FCM 依附元件:
      pod 'FirebaseMessaging'
    2. firebase.frameworkfirebase_messaging.framework 架構從 Firebase C++ SDK 拖曳至 Xcode 專案。
  3. 設定 Xcode 專案以啟用推播通知:

    1. 導覽器區域選取專案。
    2. 「Editor」區域選取專案目標。
    3. 選取「編輯器」區域中的「一般」分頁標籤

      1. 向下捲動至「Linked Framework and Libraries」,然後按一下「+」按鈕新增架構。
      2. 在隨即顯示的視窗中,捲動至「User 通知.framework」,按一下該項目,然後按一下「Add」

        此架構只會顯示在 Xcode v8 以上版本中,且這個程式庫需要此架構。

    4. 選取「Editor」區域的「Capabilities」分頁標籤

      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++ 程式庫回呼,您需要覆寫活動中的 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 需要替換為 cusom 事件監聽器服務。方法是移除預設的 ListenerService 並新增自訂 Service,方法是在專案的 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);

設定這個值後,每次重新啟動的應用程式都會保留這個值。

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

如要為應用程式新增其他進階行為,請參閱從應用程式伺服器傳送訊息的指南:

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