瞭解訊息傳送方式

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

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

本頁所述報表工具都需要 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)
• 應用程式
• 自訂數據分析標籤

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

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

數據分析標籤是 ^[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 分析資料、將資料匯出至其他雲端服務供應商，或將資料用於自訂機器學習模型。無論訊息類型為何，或訊息是透過 API 或 Notifications 編寫工具傳送，匯出至 BigQuery 的資料都會包含所有可用的訊息資料。

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

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

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

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

啟用警示通知的遞送資料匯出功能

由於只有快訊通知可以觸發通知服務應用程式擴充功能，因此您必須在應用程式中新增通知服務擴充功能，並在服務擴充功能中呼叫這個 API，才能啟用顯示訊息追蹤功能。請參閱 Apple 的說明文件，瞭解如何修改新送達通知中的內容。

每收到一則通知，就必須執行以下呼叫：

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

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

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

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

以下各節提供範例，說明您可以在 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;