瞭解訊息傳送方式

FCM 提供三組工具，協助您深入分析訊息傳送情形：

• Firebase 控制台訊息傳送報告
• 來自 Firebase Cloud Messaging Data API 的匯總 Android SDK 提交指標
• 將完整資料匯出至 Google BigQuery

本頁所述的報表工具都需要 Google Analytics 才能使用 才能正常運作如果您的專案未啟用 Google Analytics，可以在 Firebase 專案設定的「整合」分頁中進行設定。

請注意，由於需要匯出大量數據，因此這頁面上許多統計資料的報表可能會延遲至多 24 小時才會顯示。

郵件傳送報告

在 報表 Firebase 控制台中的分頁，會顯示 以下有關傳送給 Android 或 Apple 平台 FCM SDK 的訊息資料。 包括透過通知編輯器和 FCM API 傳送的項目：

• 傳送：資料訊息或通知訊息已排入傳送佇列，或已成功傳送至 APN 等第三方服務。查看訊息的生命週期 瞭解詳情
• Received (僅適用於 Android 裝置)：應用程式已收到資料訊息或通知訊息。如果接收端 Android 裝置已安裝 FCM SDK 18.0.1 以上版本，就會提供這項資料。
• 曝光次數 (僅適用於 Android 裝置上的通知訊息)：應用程式在背景運作時，裝置上顯示的通知次數。
• 開啟 — 使用者開啟了通知訊息。僅針對應用程式在背景執行時收到的通知回報。

系統會針對含有通知酬載的所有訊息提供這項資料 且所有已加上標籤 資料訊息。 如要進一步瞭解標籤，請參閱「在訊息中加入數據分析標籤」。

查看訊息報表時，您可以設定顯示資料的日期範圍 就能匯出成 CSV您也可以根據下列條件進行篩選：

• 平台 (iOS 或 Android)
• 應用程式
• 自訂數據分析標籤

為訊息加入數據分析標籤

為訊息加上標籤是一項實用的自訂分析功能， 可依標籤或標籤組合篩選放送統計資料。您可以新增 方法是設定標籤 找到 fcmOptions.analyticsLabel 欄位， message 物件，或在 特定平台的 AndroidFcmOptions 或 ApnsFcmOptions 欄位

Analytics 標籤是字串，格式為 ^[a-zA-Z0-9-_.~%]{1,50}$。 標籤可包含大小寫英文字母 數字以及下列符號：

• -
• ~
• %

長度上限為 50 個半形字元。您每天最多可以指定 100 個不重複的標籤。 如果郵件的標籤超過此上限，系統就不會回報。

在 Firebase 控制台訊息「Reports」分頁中，您可以搜尋所有現有標籤的清單，並逐一套用或組合套用這些標籤，藉此篩選顯示的統計資料。

透過 FCM Data API 的匯總傳送資料

Firebase Cloud Messaging Data API 可讓您擷取資訊，協助您瞭解針對 Android 應用程式指定的訊息要求結果。這個 API 會提供專案中所有支援資料收集功能的 Android 裝置匯總資料。這包括詳細資料，說明未延遲傳送的訊息百分比，以及 Android 傳輸層中延遲或遺失的訊息數量。評估這些資料可發現郵件傳送中的廣泛趨勢，有助您 找出提高傳送要求效能的有效方法。如要瞭解報表的日期範圍可用性，請參閱匯總資料時間軸。

API 會提供特定應用程式可用的所有資料。請參閱 API 參考資料說明文件。

資料是如何細分？

傳送資料會按照應用程式、日期和數據分析標籤細分。 對 API 的呼叫會傳回 取得各種資料。適用對象 例如，單一 androidDeliveryData JSON 物件應如下所示：

 {
  "appId": "1:23456789:android:a93a5mb1234efe56",
  "date": {
    "year": 2021,
    "month": 1,
    "day": 1
  },
  "analyticsLabel": "foo",
  "data": {
    "countMessagesAccepted": "314159",
    "messageOutcomePercents": {
      "delivered": 71,
      "pending": 15
    },
   "deliveryPerformancePercents": {
      "deliveredNoDelay": 45,
      "delayedDeviceOffline": 11
    }
  }

如何解讀指標

傳送資料會列出符合下列各項指標的訊息百分比。單一訊息可能適用於多項指標。 由於資料收集方式和匯總指標的細緻程度有限制，部分訊息結果並未列入指標，因此下方百分比的總和不會等於 100%。

接受的訊息數

資料集中唯一的計數就是 FCM 允許您的應用程式提交至 Android 裝置。所有百分比都會使用這個值做為分母。請注意，這個計數不會納入針對已停用裝置上使用情形和診斷資訊收集功能的使用者傳送的訊息。

訊息結果百分比

MessageOutcomePercents 物件中包含的欄位會提供訊息要求的結果資訊。這些類別彼此互斥。這項工具可以回答「我的訊息是否已送達？」和「導致訊息遭到捨棄的原因為何？」等問題。

舉例來說，如果 droppedTooManyPendingMessages 欄位的值很高， 表示應用程式執行個體接收 無法收合的訊息 超過 FCM 的待審核訊息數量上限 (100 則)。 為避免這種情況，請確保應用程式能夠處理對 onDeletedMessages 的呼叫，並考慮傳送可摺疊的訊息。同樣地，droppedDeviceInactive 的百分比高，可能表示您需要更新伺服器上的註冊權杖，刪除過期的權杖，並取消訂閱主題。如需這方面的最佳做法，請參閱「管理 FCM 註冊權杖」。

推送成效百分比

DeliveryPerformancePercents 中的欄位 物件提供成功傳送的訊息相關資訊。這項服務 回答「我的郵件有延遲嗎？」和 「為什麼郵件會延遲送達？」舉例來說，如果指定值是 delayedMessageThrottled 可能明顯表示您超出 每部裝置的上限、 且應調整您傳送訊息的速率。

訊息深入分析百分比

這個物件提供所有傳送訊息的額外資訊。priorityLowered 欄位表示已接受的郵件中，優先順序從 HIGH 降至 NORMAL 的百分比。如果這個值偏高，請試著減少傳送優先順序較高的郵件，或確保 當您傳送重要性較高的郵件時，一律會顯示通知。詳情請參閱郵件優先順序說明文件

這項資料與匯出至 BigQuery 的資料有何不同？

BigQuery Export 會提供個別訊息記錄，說明系統透過 FCM 後端，以及在裝置上的 SDK 中傳送訊息 (步驟 2 和 4 FCM 架構)。這項資料可用於確認個別訊息是否已接受並送達。請參閱下一節，進一步瞭解 BigQuery 資料匯出功能。

相較之下，Firebase Cloud Messaging Data API 則會提供匯總詳細資料 有關 Android 傳輸層安全標準 (或 FCM 架構)。 這項資料可深入瞭解從 FCM 後端傳送至 Android SDK 的訊息。這項功能特別適合用於顯示趨勢，說明為何郵件在傳輸期間延遲或遭到捨棄。

在某些情況下，這兩個資料集可能會因為下列原因而無法完全相符：

• 匯總指標只會對部分訊息的一部分進行取樣
• 匯總指標會四捨五入
• 我們不會顯示低於隱私權門檻的指標
• 最佳化調整方式，導致部分訊息結果遺失 能因應大量流量

API 的限制

匯總資料時間軸

API 會傳回 7 天的歷來資料；不過，這個 API 傳回的資料最多會延遲 5 天。舉例來說，在 1 月 20 日，系統會提供 1 月 9 日至 1 月 15 日的資料，但不會提供 1 月 16 日或之後的資料。除此之外，我們也會盡可能提供資料。如果發生以下情況： 資料服務中斷時，FCM 會著手修正，不會在此後補充資料 問題已解決在較大規模的停機期間，資料可能會無法使用一週或更久的時間。

資料涵蓋率

Firebase Cloud Messaging Data API 提供的指標能 針對廣泛的郵件傳送趨勢提供深入分析。但他們並未 提供所有郵件情境 100% 的涵蓋率下列情況 指標不會反映已知結果

過期訊息

如果存留時間 (TTL) 過期 在指定記錄日期之後，訊息便不會視為 這個日期的 droppedTtlExpired。

傳送至非使用中裝置的訊息

如果訊息是傳送至閒置裝置，則訊息不一定會顯示在資料集中 以便靈活運用這可能會導致 droppedDeviceInactive 和 pending 欄位出現錯誤計數。

傳送給具有特定使用者偏好的裝置的訊息

如果使用者已停用裝置上的使用和診斷資訊收集功能，系統就不會根據使用者的偏好設定，將他們的訊息納入計算。

四捨五入和最低值

FCM 刻意無條件捨去，資料量不大時的情況則會排除 就這樣。

BigQuery 資料匯出

您可以將訊息資料匯出至 BigQuery，以便進一步分析。BigQuery 能讓您使用 BigQuery SQL 分析資料，再匯出至其他雲端 或運用這些資料建立自訂機器學習模型匯出至 BigQuery 包含訊息的所有可用資料，無論 訊息類型、訊息是透過 API 傳送 通知編輯器

如果訊息是傳送至採用下列 FCM SDK 最低版本的裝置，您可以選擇啟用應用程式的訊息傳送資料匯出功能：

• Android 20.1.0 以上版本。
• iOS 8.6.0 以上版本
• Firebase Web SDK 9.0.0 以上版本

如要進一步瞭解如何為 Android 和 iOS 啟用資料匯出功能，請參閱下文。

如要開始使用，請將專案連結至 BigQuery：

1. 選擇下列其中一種做法：

   • 開啟 Notifications 編寫工具，然後點選頁面底部的「Access BigQuery」。

   • 從 整合 頁面，在 Firebase控制台中，按一下 BigQuery 中的連結 資訊卡

     這個頁面會顯示所有使用者的 FCM 匯出選項 專案中已啟用 FCM 的應用程式。

2. 按照畫面上的指示啟用 BigQuery。

詳情請參閱「將 Firebase 連結至 BigQuery」一文。

為 Cloud Messaging 啟用 BigQuery 匯出功能時：

• Firebase 會將資料匯出至 BigQuery。注意事項 資料首次匯出最多可能需要 48 小時 完成。

  • 您最多可以手動排定資料補充作業，最久可補充過去 30 天的資料。

• 建立資料集後，位置 無法變更，但可將資料集複製到其他位置 或在不同位置手動移動 (重新建立) 資料集學習 詳情請參閱變更資料集位置。

• Firebase 會定期將資料從 Firebase 專案同步至 BigQuery。這些每日匯出作業會在太平洋時間凌晨 4 點開始，通常會在 24 小時內完成。

• 根據預設，您專案中的所有應用程式都會連結至 BigQuery，您之後才加進專案的應用程式也統統會自動與 BigQuery 連結。你可以 管理該傳送資料的應用程式。

如要停用 BigQuery 匯出功能， 取消連結專案 (在 Firebase 控制台中)。

啟用郵件傳送資料匯出功能

採用 FCM SDK 8.6.0 以上版本的 iOS 裝置 可以啟用應用程式的訊息傳送資料匯出功能。FCM 支援警示和背景通知的資料匯出作業。啟用這些選項前，您必須先為專案建立 FCM-BigQuery 連結，如BigQuery 資料匯出所述。

啟用快訊通知的傳送資料匯出功能

由於只有快訊通知可以觸發通知服務應用程式擴充功能，因此您必須在應用程式中新增通知服務擴充功能，並在服務擴充功能中呼叫這個 API，才能啟用顯示訊息追蹤功能。詳情請見 Apple 的「在 Newly Delivered Notifications 中修改內容」說明文件。

每次收到通知時，都必須發出以下呼叫：

// For alert notifications, call the API inside the service extension:
class NotificationService: UNNotificationServiceExtension {
  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
  Messaging.extensionHelper()
      .exportDeliveryMetricsToBigQuery(withMessageInfo:request.content.userInfo)
  }
}

// For alert notifications, call the API inside the service extension:
@implementation NotificationService
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request
                   withContentHandler:(void (^)(UNNotificationContent *_Nonnull))contentHandler {
  [[FIRMessaging extensionHelper] exportDeliveryMetricsToBigQueryWithMessageInfo:request.content.userInfo];
}
@end

如果您使用 HTTP v1 API 建構傳送要求，請務必在酬載物件中指定 mutable-content = 1。

啟用背景通知的遞送資料匯出功能

對於在應用程式於前景或背景運作時收到的背景訊息， 可以在主要應用程式的資料訊息處理常式中，呼叫資料匯出 API。 您必須為收到的每則通知發出此呼叫：

// For background notifications, call the API inside the UIApplicationDelegate or NSApplicationDelegate method:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
  Messaging.extensionHelper().exportDeliveryMetricsToBigQuery(withMessageInfo:userInfo)
}

// For background notifications, call the API inside the UIApplicationDelegate or NSApplicationDelegate method:
@implementation AppDelegate
- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
          fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  [[FIRMessaging extensionHelper] exportDeliveryMetricsToBigQueryWithMessageInfo:userInfo];
}
@end

哪些資料會匯出至 BigQuery？

請注意，指定過時的權杖或無效註冊資料可能會誇大這些統計資料。

匯出資料表的結構定義如下：

匯出的資料可做什麼用途？

以下各節提供範例，說明您可以針對匯出的 FCM 資料，在 BigQuery 中執行哪些查詢。

依應用程式計算傳送的訊息數

SELECT app_name, COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_id != ''
GROUP BY 1;

計算訊息指定的不重複應用程式執行個體數

SELECT COUNT(DISTINCT instance_id)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED';

計算已傳送的通知訊息數

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DISPLAY_NOTIFICATION';

計算傳送的資料訊息

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND message_type = 'DATA_MESSAGE';

計算傳送至主題或廣告活動的訊息

SELECT COUNT(1)
FROM `project ID.firebase_messaging.data`
WHERE
  _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
  AND event = 'MESSAGE_ACCEPTED'
  AND bulk_id = your bulk id AND message_id != '';

如要追蹤傳送給特定主題的訊息事件，請將這項查詢修改為 以 AND message_id = <your message id>; 取代 AND message_id != ''。

計算特定主題或廣告活動的發散時間

擴散傳遞開始時間是指收到原始要求的時間，結束時間是 time 是最近一次個別訊息指定單一例項的時間

SELECT
  TIMESTAMP_DIFF(
    end_timestamp, start_timestamp, MILLISECOND
  ) AS fanout_duration_ms,
  end_timestamp,
  start_timestamp
FROM (
    SELECT MAX(event_timestamp) AS end_timestamp
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND event = 'MESSAGE_ACCEPTED'
      AND bulk_id = your bulk id
  ) sent
  CROSS JOIN (
    SELECT event_timestamp AS start_timestamp
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND event = 'MESSAGE_ACCEPTED'
      AND bulk_id = your bulk id
      AND message_type = 'TOPIC'
  ) initial_message;

已傳送的訊息百分比

SELECT
  messages_sent,
  messages_delivered,
  messages_delivered / messages_sent * 100 AS percent_delivered
FROM (
    SELECT COUNT(DISTINCT CONCAT(message_id, instance_id)) AS messages_sent
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND event = 'MESSAGE_ACCEPTED'
  ) sent
  CROSS JOIN (
    SELECT COUNT(DISTINCT CONCAT(message_id, instance_id)) AS messages_delivered
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND (event = 'MESSAGE_DELIVERED'
      AND message_id
      IN (
        SELECT message_id FROM `project ID.firebase_messaging.data`
        WHERE
          _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
          AND event = 'MESSAGE_ACCEPTED'
        GROUP BY 1
      )
  ) delivered;

追蹤指定訊息 ID 和例項 ID 的所有事件

SELECT *
FROM `project ID.firebase_messaging.data`
WHERE
    _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
    AND message_id = 'your message id'
    AND instance_id = 'your instance id'
ORDER BY event_timestamp;

計算指定訊息 ID 和執行個體 ID 的延遲時間

SELECT
  TIMESTAMP_DIFF(
    MAX(delivered_time), MIN(accepted_time), MILLISECOND
  ) AS latency_ms
FROM (
    SELECT event_timestamp AS accepted_time
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD')
      AND message_id = 'your message id'
      AND instance_id = 'your instance id'
      AND event = 'MESSAGE_ACCEPTED'
  ) sent
  CROSS JOIN (
    SELECT event_timestamp AS delivered_time
    FROM `project ID.firebase_messaging.data`
    WHERE
      _PARTITIONTIME = TIMESTAMP('date as YYYY-MM-DD') AND
      message_id = 'your message id' AND instance_id = 'your instance id'
      AND (event = 'MESSAGE_DELIVERED'
  ) delivered;