如要使用 C++ 編寫跨平台 Firebase Cloud Messaging 用戶端應用程式,請使用 Firebase Cloud Messaging API。C++ SDK 適用於 Android 和 Apple 平台,但每個平台都需要額外設定。
設定 Firebase 和 FCM SDK
如果您尚未將 Firebase 新增至 C++ 專案,請先新增。
請參閱連結的設定說明,瞭解使用 Firebase C++ SDK 的裝置和應用程式需求,包括建議使用 CMake 建構應用程式。
在專案層級的
build.gradle
檔案中,請務必在buildscript
和allprojects
區段中加入 Google 的 Maven 存放區。
建立 Firebase 應用程式物件,並傳遞 JNI 環境和活動:
app = ::firebase::App::Create(::firebase::AppOptions(), jni_env, activity);
定義實作
firebase::messaging::Listener
介面的類別。初始化 FCM,並傳遞應用程式和建構的接聽程式:
::firebase::messaging::Initialize(app, listener);
如果應用程式使用 Google Play 服務 SDK,請先檢查裝置是否具備相容的 Google Play 服務 APK,再存取相關功能。詳情請參閱「檢查 Google Play 服務 APK」。
- 如果您尚未將 Firebase 新增至 C++ 專案,請先新增。接著,請設定專案以使用 FCM:
- 在專案的 Podfile 中,新增 FCM 依附元件:
pod 'FirebaseMessaging'
- 將
firebase.framework
和firebase_messaging.framework
架構從 Firebase C++ SDK 拖曳至 Xcode 專案。
- 在專案的 Podfile 中,新增 FCM 依附元件:
將 APNs 驗證金鑰上傳至 Firebase。 如果沒有 APNs 驗證金鑰,請務必在 Apple 開發人員會員中心建立。
-
在 Firebase 控制台的專案中,依序選取齒輪圖示、「專案設定」和「Cloud Messaging」分頁標籤。
-
在「iOS 應用程式設定」下方的「APNs 驗證金鑰」, 按一下「上傳」 按鈕。
-
瀏覽至您儲存金鑰的位置,選取金鑰,然後按一下「開啟」。新增金鑰的 ID (可在 Apple Developer Member Center 中取得),然後按一下「上傳」。
-
設定 Xcode 專案,啟用推播通知:
- 從「Navigator area」選取專案。
- 從「編輯器區域」選取專案目標。
在「編輯器區域」中選取「一般」分頁標籤。
- 向下捲動至「Linked Frameworks and Libraries」(連結的架構和程式庫),然後按一下「+」按鈕新增架構。
在顯示的視窗中,捲動至「UserNotifications.framework」,點選該項目,然後按一下「Add」。
這個架構只會顯示在 Xcode v8 以上版本,且是這個程式庫的必要架構。
在「編輯器區域」中選取「功能」分頁標籤。
- 將「推播通知」切換為「開啟」。
- 向下捲動至「背景模式」,然後切換為「開啟」。
- 選取「背景模式」下的「遠端通知」。
建立 Firebase 應用程式物件:
app = ::firebase::App::Create(::firebase::AppOptions());
定義實作
firebase::messaging::Listener
介面的類別。初始化 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
:
<?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::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 傳送下游訊息和主題訊息。如要進一步瞭解這項功能,請參閱快速入門範例,您可以下載、執行及查看該範例。
如要為應用程式新增其他進階行為,請參閱下列指南,瞭解如何從應用程式伺服器傳送訊息:
請注意,您需要伺服器實作才能使用這些功能。