瞭解訊息傳送方式

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

• Firebase 控制台訊息傳送報表
• 來自以下項目的匯總 Android SDK 放送指標： Firebase 雲端通訊資料 API
• 全面將資料匯出至 Google BigQuery

注意： 本頁中的工具主要用於評估訊息是否成功，以及 策略。如果您的目標是要排解郵件持續傳送失敗的問題，請參閱 FCM 疑難排解工具。

本頁所述的報表工具都必須啟用 Google Analytics 才能使用 才能正常運作如果專案未啟用 Google Analytics， 請前往 GCP 控制台 整合 找到「專案設定」分頁

請注意，系統回報的是這個頁面上許多統計資料 如果批次處理數據分析資料，最多可能會延遲 24 小時才生效。

郵件傳送報告

在 報表 分頁，即可查看 以下有關傳送給 Android 或 Apple 平台 FCM SDK 的訊息資料。 包括透過通知編輯器和 FCM API 傳送的項目：

• 傳送 — 資料訊息或通知訊息已排入佇列 或已順利傳送給 APN 等第三方服務 配送服務查看訊息的生命週期 瞭解詳情
• 已接收 (僅適用於 Android 裝置)：資料訊息或 通知訊息。可取得這項資料 接收端搭載 FCM SDK 18.0.1 或 或 100% 以上
• 曝光次數 (僅適用於 Android 裝置上的通知訊息) — 當應用程式處於以下狀態時，裝置上顯示了螢幕通知 在背景執行
• 開啟 — 使用者開啟了通知訊息。回報對象 當應用程式在背景執行時收到的通知。

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

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

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

為訊息加入數據分析標籤

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

重要事項： 如要使用這項功能，您必須先加入 Analytics SDK 並在應用程式內啟用 資料共用 掌握實用知識數據分析標籤 無法顯示資料訊息的所有類型統計資料。

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

• -
• ~
• %

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

在 Firebase 控制台的訊息「報表」分頁中，您可以搜尋 列出所有現有標籤的清單，然後單獨套用或組合標籤來篩選 顯示的統計資料。

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

Firebase 雲端通訊資料 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 註冊權杖 提供負責任的 AI 技術

交付成效百分比

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 的設定。

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

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

   • 未解決 通知編輯器 按一下頁面底部的「存取 BigQuery」。

   • 從 整合 頁面，在「BigQuery」中按一下「連結」 資訊卡

     這個頁面會顯示以下項目的 FCM 匯出選項： 專案中已啟用 FCM 的應用程式。

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

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

為雲端通訊啟用 BigQuery Export 功能後：

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

  • 您可以手動排定資料補充作業 過去 30 天內的資料

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

• Firebase 會定期同步處理 Firebase 專案中的 BigQuery。這些每日匯出作業會在太平洋時間凌晨 4 點開始執行 通常在 24 小時內完成

• 根據預設，專案中的所有應用程式會連結至 BigQuery 和 您稍後加入專案的應用程式會自動連結至 BigQuery。你可以 管理該傳送資料的應用程式。

如要停用 BigQuery Export 取消連結專案 。

注意： 從 FCM 匯出資料不會產生費用。 BigQuery 提供大量的免費用量限制。詳情請參閱 BigQuery 定價，或是 BigQuery 沙箱。

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

iOS Android 網頁

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

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

因為只有快訊通知可觸發通知服務應用程式 擴充功能，您必須在應用程式和來電中加入通知服務擴充功能 啟用顯示訊息追蹤功能詳情請見 Apple 的「在 Newly Delivered Notifications 中修改內容」說明文件。

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

Swift

// 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)
  }
}

Objective-C

// 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。 每次收到通知時都必須發出這項呼叫：

Swift

// 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)
}

Objective-C

// 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？

請注意，指定過期或無效的註冊憑證可能會導致部分憑證 這些統計資料。

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

_PARTITIONTIME	TIMESTAMP	這個虛擬資料欄含有當天開始的時間戳記 (世界標準時間) 也就是資料載入時所在的位置如果是 YYYYMMDD 分區，這個虛擬資料欄 包含 TIMESTAMP('YYYY-MM-DD') 的值。
event_timestamp	TIMESTAMP	伺服器記錄的事件時間戳記
專案編號	INTEGER	專案編號可識別傳送訊息的專案
message_id	STRING	郵件 ID 可用於識別郵件。根據應用程式 ID 產生 時間戳記，郵件 ID 在某些情況下可能會是全域唯一的值。
instance_id	STRING	接收訊息的應用程式專屬 ID (如果有的話)。可以 執行個體 ID 或 Firebase 安裝 ID。
message_type	STRING	訊息的類型。可以是通知訊息或資料訊息。主題 用於識別主題或廣告活動傳送的原始訊息； 後續的訊息可能是通知訊息或資料訊息
sdk_platform	STRING	接收者應用程式的平台
應用程式名稱	STRING	Android 應用程式的套件名稱，或 iOS 應用程式的軟體包 ID
收合鍵	STRING	收合鍵會指出可收合的一組訊息。 未連線的裝置時，系統只會顯示最新一則收合畫面的訊息 金鑰已排入最終傳送佇列
優先順序	INTEGER	訊息的優先順序。有效值為「normal」和「高」。iOS 裝置 都會對應至 APN 優先順序 5 和 10
文字轉語音	INTEGER	這個參數可指定訊息的保留時間 (以秒為單位) FCM 儲存空間 (如果裝置處於離線狀態)
主題	STRING	傳送訊息的主題名稱 (如適用)
大量 ID	INTEGER	大量 ID 可用來辨識一系列相關訊息，例如特定訊息 傳送至主題
事件	STRING	事件的類型。 可能的值包括： MESSAGE_ACCEPTED：訊息已由 FCM 伺服器接收， 為有效值； MESSAGE_DELIVERED：訊息已傳送至應用程式的 FCM SDK 裝置。根據預設，這個欄位不會套用。如要啟用，請按照 操作說明：setDeliveryMetricsExportToBigQuery(boolean)。 MISSING_REGISTRATIONS：請求因缺少所需項目而遭到拒絕 註冊； UNAUTHORIZED_REGISTRATION：郵件遭拒，因為寄件者： 無權 傳送給註冊者； MESSAGE_RECEIVED_INTERNAL_ERROR： 處理訊息要求； MISMATCH_SENDER_ID：傳送訊息的要求遭到拒絕，因為 與送出訊息的寄件者 ID 不符 最終點 QUOTA_EXCEEDED：傳送訊息的要求遭到拒絕，因為 配額不足； INVALID_REGISTRATION：傳送訊息的要求已遭到拒絕，因為 註冊無效； INVALID_PACKAGE_NAME：傳送訊息的要求已遭到拒絕，因為 套件名稱無效； INVALID_APNS_CREDENTIAL：傳送訊息的要求已遭到拒絕，原因如下： APNs 憑證無效； INVALID_PARAMETERS：傳送訊息的要求遭到拒絕，因為 參數無效； PAYLOAD_TOO_LARGE：傳送訊息的要求遭到拒絕，因為 超過限制； AUTHENTICATION_ERROR：傳送訊息的要求遭到拒絕，因為 驗證錯誤 (檢查用來傳送訊息的 API 金鑰)； INVALID_TTL：傳送訊息的要求因無效而遭到拒絕 存留時間。
Analytics 標籤	STRING	使用 HTTP v1 API 傳送訊息時，您可以設定分析標籤 以便進行分析

你可以如何處理匯出的資料？

下列各節提供可在 BigQuery 中執行的查詢範例 與匯出的 FCM 資料相比的結果

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

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;