瞭解訊息傳送方式

FCM 提供三套工具，協助您深入瞭解訊息傳送情況：

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

注意： 本頁中的工具可廣泛評估訊息成效和策略。如果您想排解持續發生的郵件傳送失敗問題，請參閱 FCM 疑難排解工具。

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

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

郵件傳送報告

在 Firebase 控制台的「Reports」分頁中，您可以查看傳送至 Android 或 Apple 平台 FCM SDK 的訊息相關資料，包括透過 Notifications 組合工具和 FCM API 傳送的訊息：

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

這項資料適用於所有含有通知酬載的訊息，以及所有標記的資料訊息。如要進一步瞭解標籤，請參閱「在訊息中加入數據分析標籤」。

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

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

在訊息中加入數據分析標籤

為訊息加上標籤對於自訂分析非常有用，可讓您依標籤或標籤組篩選提交統計資料。您可以透過在 message 物件或特定平台的 AndroidFcmOptions 或 ApnsFcmOptions 欄位中設定 fcmOptions.analyticsLabel 欄位，為透過 HTTP v1 API 傳送的任何訊息新增標籤。

重要事項： 如要使用這項功能，您必須在應用程式中加入 Analytics SDK，並透過 Firebase 啟用資料分享功能。您必須使用數據分析標籤，才能顯示資料訊息的所有統計資料類型。

數據分析標籤是 ^[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 匯出內容會提供個別訊息記錄，說明 FCM 後端接受訊息，以及裝置上的 SDK 傳送訊息 (請參閱 FCM 架構的步驟 2 和 4)。這項資料可用於確認個別訊息是否已接受並送達。請參閱下一節，進一步瞭解 BigQuery 資料匯出功能。

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

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

• 匯總指標只會抽樣取得部分訊息
• 匯總指標會四捨五入
• 我們不會顯示低於隱私權門檻的指標
• 由於我們在管理大量流量時採用最佳化做法，因此部分訊息成效未顯示。

API 的限制

匯總資料時間軸

API 會傳回 7 天的歷來資料，但這個 API 傳回的資料最多會延遲 5 天。舉例來說，在 1 月 20 日，系統會提供 1 月 9 日至 1 月 15 日的資料，但不會提供 1 月 16 日或之後的資料。此外，系統會盡力提供資料。如果發生資料中斷情形，FCM 會嘗試修正，並在問題解決後不會補充資料。在較大規模的停機期間，資料可能會無法使用一週或更久的時間。

資料涵蓋率

Firebase 雲端通訊資料 API 提供的評估指標，可讓您深入瞭解訊息傳送的整體趨勢。不過，這些測試並未涵蓋所有訊息情境。以下是指標未反映的已知結果。

過期訊息

如果存留時間 (TTL) 在指定記錄日期結束後到期，系統就不會在該日期將訊息計為 droppedTtlExpired。

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

傳送至閒置裝置的訊息是否會顯示在資料集中，取決於訊息採用的資料路徑。這可能會導致 droppedDeviceInactive 和 pending 欄位出現錯誤計數。

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

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

四捨五入和最低值

FCM 會刻意捨去數字，並排除數量不夠大的計數。

BigQuery 資料匯出

您可以將訊息資料匯出至 BigQuery 進行進一步分析。您可以使用 BigQuery SQL 分析資料、將資料匯出至其他雲端服務供應商，或將資料用於自訂機器學習模型。匯出至 BigQuery 的資料包含訊息的所有可用資料，不論訊息類型為何，或訊息是透過 API 或 Notifications 編寫工具傳送，皆是如此。

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

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

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

注意： 請確認您具備資料存取資格，才能查看或管理匯出將資料匯出至 BigQuery 的相關設定。

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

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

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

   • 在 Firebase 控制台的「Integrations」頁面中，按一下「BigQuery」資訊卡中的「Link」。

     這個頁面會顯示專案中所有支援 FCM 的應用程式的 FCM 匯出選項。

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

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

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

• Firebase 會將資料匯出至 BigQuery。請注意，匯出資料的初始傳播作業最多可能需要 48 小時才能完成。

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

• 建立資料集後，該資料集的位置就無法再變更，不過您可以將資料集複製到其他位置，或將資料集手動移動 (重新建立) 至其他位置。詳情請參閱「變更資料集位置」。

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

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

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

注意： 從 FCM 匯出資料不會產生費用，BigQuery 也提供豐富的免費使用限制。請參閱 BigQuery 定價或 BigQuery 沙箱。

啟用訊息放送資料匯出功能

iOS Android 網頁

搭載 FCM SDK 20.1.0 以上版本的 Android 裝置，可以啟用應用程式的訊息傳送資料匯出功能。根據預設，系統會在應用程式層級停用資料匯出功能。您可以透過程式輔助方式在應用程式例項層級啟用這項功能，要求使用者授權分析其訊息傳送資料 (建議做法)。如果同時設定這兩個值，應用程式執行個體層級的值會覆寫應用程式層級的值。

啟用這些選項前，您必須先為專案建立 FCM-BigQuery 連結，如BigQuery 資料匯出所述。

為應用程式執行個體啟用提交資料匯出功能

在大多數情況下，我們建議您只在應用程式執行個體層級啟用訊息傳送資料匯出功能，並在應用程式層級停用這項功能。

 FirebaseMessaging.getInstance().setDeliveryMetricsExportToBigQuery(true)

為應用程式啟用提交資料匯出功能

如果您偏好在應用程式層級啟用匯出功能，請務必不呼叫 setDeliveryMetricsExportToBigQuery 方法，並將下列屬性新增至應用程式資訊清單中的應用程式物件：

<application>
  <meta-data android:name="delivery_metrics_exported_to_big_query_enabled"
      android:value="true" />
</application>

哪些資料會匯出至 BigQuery？

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

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

_PARTITIONTIME	TIMESTAMP	這個虛擬資料欄包含載入資料當天 (以世界標準時間表示) 的起始時間戳記。對於 YYYYMMDD 區隔，這個虛擬資料欄包含 TIMESTAMP('YYYY-MM-DD') 的值。
event_timestamp	TIMESTAMP	伺服器記錄的事件時間戳記
project_number	INTEGER	專案編號可識別傳送訊息的專案
message_id	STRING	郵件 ID 可用於識別郵件。系統會根據應用程式 ID 和時間戳記產生訊息 ID，在某些情況下，該 ID 可能並非全域唯一。
instance_id	STRING	訊息傳送至的應用程式專屬 ID (如有)。可以是執行個體 ID 或 Firebase 安裝 ID。
message_type	STRING	訊息類型。可以是通知訊息或資料訊息。主題用於識別主題或廣告活動傳送的原始訊息；後續訊息則是通知或資料訊息。
sdk_platform	STRING	接收端應用程式的平台
app_name	STRING	Android 應用程式的套件名稱，或 iOS 應用程式的軟體包 ID
collapse_key	STRING	折疊鍵可用於標示可折疊的一組訊息。當裝置未連線時，只有具有指定折疊鍵的最後一個訊息會排入佇列，以便最終傳送
優先順序	INTEGER	訊息的優先順序。有效值為「normal」和「high」。在 iOS 上，這些會對應至 APN 優先順序 5 和 10
ttl	INTEGER	這個參數會指定訊息在裝置離線時，應保留在 FCM 儲存空間中的時間長度 (以秒為單位)
主題	STRING	訊息傳送至的主題名稱 (如適用)
bulk_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 與端點所宣告的 ID 不符； QUOTA_EXCEEDED：傳送訊息的要求遭拒，原因是配額不足； INVALID_REGISTRATION：由於註冊無效，導致傳送訊息的要求遭到拒絕。 INVALID_PACKAGE_NAME：傳送訊息的要求遭到拒絕，原因是套件名稱無效； INVALID_APNS_CREDENTIAL：由於 APNS 憑證無效，因此傳送訊息的要求遭到拒絕； INVALID_PARAMETERS：傳送訊息的要求因參數無效而遭拒； PAYLOAD_TOO_LARGE：由於酬載大於限制值，因此訊息傳送要求遭到拒絕； AUTHENTICATION_ERROR：由於驗證錯誤，系統已拒絕傳送訊息的要求 (請檢查用於傳送訊息的 API 金鑰)； INVALID_TTL：傳送訊息的要求因 TTL 無效而遭到拒絕。
analytics_label	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 != '' 替換為 AND message_id = <your message id>;。

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

分支開始時間是收到原始要求的時間，而結束時間則是建立指定單一例項的最後一則個別訊息的時間。

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;