Firebase Demo Day is here! Watch demos of how to build and grow AI-powered, full stack apps using the best of Google.

本頁面由 Cloud Translation API 翻譯而成。

Switch to English

了解消息傳遞

FCM 提供三組工具來幫助您深入了解訊息傳遞：

Firebase 控制台訊息傳遞報告
來自 Firebase Cloud Messaging Data API 的聚合 Android SDK 交付指標
全面的資料匯出至 Google BigQuery

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

請記住，由於分析資料的批次處理，此頁面上的許多統計資料的報告可能會延遲長達 24 小時。

訊息傳遞報告

在 Firebase 控制台的「報告」標籤中，您可以查看發送到 Android 或 Apple 平台 FCM SDK 的訊息的以下數據，包括透過通知編輯器和 FCM API 發送的訊息：

發送 — 資料訊息或通知訊息已排隊等待傳送，或已成功傳遞至 APNs 等第三方服務進行傳送。有關詳細信息，請參閱訊息的生命週期。
已收到（僅適用於 Android 裝置）— 應用程式已收到資料訊息或通知訊息。當接收 Android 裝置安裝了 FCM SDK 18.0.1 或更高版本時，此資料可用。
印象數（僅適用於 Android 裝置上的通知訊息）— 當應用程式處於背景時，顯示通知已顯示在裝置上。
開啟 — 使用者開啟通知訊息。僅報告應用程式在背景時收到的通知。

此資料可用於所有具有通知有效負載的訊息和所有標籤的資料訊息。要了解有關標籤的更多信息，請參閱向訊息添加分析標籤。

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

平台（iOS 或 Android）
應用程式
自訂分析標籤

向訊息新增分析標籤

標記訊息對於自訂分析非常有用，允許您按標籤或標籤集過濾傳遞統計資訊。您可以透過在訊息物件中或在特定於平台的AndroidFcmOptions或ApnsFcmOptions欄位中設定fcmOptions.analyticsLabel字段，向透過 HTTP v1 API 發送的任何訊息新增標籤。

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

最大長度為 50 個字元。每天最多可以指定 100 個唯一標籤；新增的標籤超出該限制的訊息將不會被報告。

在 Firebase 控制台訊息傳遞「報告」標籤中，您可以搜尋所有現有標籤的列表，並單獨或組合應用它們來過濾顯示的統計資料。

透過 FCM 數據 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 雲端訊息資料 API 提供了有關 Android 傳輸層（或FCM 架構的第 3 步）中具體發生的情況的匯總詳細資訊。該數據專門提供了對從 FCM 後端到 Android SDK 的訊息傳遞的深入了解。它對於顯示訊息在傳輸過程中延遲或遺失的原因的趨勢特別有用。

在某些情況下，由於以下原因，兩個資料集可能不完全匹配：

聚合指標僅對所有訊息的一部分進行採樣
聚合指標已四捨五入
我們不會提供低於隱私閾值的指標
由於我們管理大量流量的方式進行了最佳化，因此遺失了部分訊息結果。

API 的限制

聚合資料時間線

API將傳回7天的歷史資料；但是，該API傳回的資料最多會延遲5天。例如，1 月 20 日，1 月 9 日至 1 月 15 日的資料可用，但 1 月 16 日及之後的資料不可用。此外，數據是盡最大努力提供的。如果發生資料中斷，FCM 將努力向前修復，問題修復後不會回填資料。在較大的中斷中，資料可能會在一周或更長時間內不可用。

數據覆蓋範圍

Firebase Cloud Messaging Data API 提供的指標旨在深入了解訊息傳遞的廣泛趨勢。但是，它們並不能 100% 覆蓋所有訊息場景。以下場景是未反映在指標中的已知結果。

折疊的消息

已被另一則訊息折疊的訊息不會出現在資料集中。

發送至非活動設備的訊息

發送到非活動設備的訊息可能會也可能不會顯示在資料集中，這取決於它們採用的資料路徑。這可能會導致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 。
- 在 Firebase 控制台的整合頁面中，點擊BigQuery卡中的連結。
  此頁面顯示專案中所有啟用 FCM 的應用程式的 FCM 匯出選項。
請依照螢幕上的指示啟用 BigQuery。

有關詳細信息，請參閱將 Firebase 連結到 BigQuery 。

當您為 Cloud Messaging 啟用 BigQuery 匯出時：

Firebase將您的資料匯出到 BigQuery。請注意，匯出資料的初始傳播可能需要長達 48 小時才能完成。
- 您可以手動安排最多過去 30 天的資料回填。
建立資料集後，位置無法更改，但您可以將資料集複製到其他位置或手動移動（重新建立）到其他位置的資料集。要了解更多信息，請參閱更改資料集位置。
Firebase 會定期將資料從 Firebase 專案同步到 BigQuery。這些每日匯出操作於太平洋時間凌晨 4:00 開始，通常在 24 小時內完成。
預設情況下，專案中的所有應用程式都會連結到 BigQuery，並且您以後新增到專案中的任何應用程式都會自動連結到 BigQuery。您可以管理哪些應用程式發送資料。

若要停用 BigQuery 匯出，請在 Firebase 控制台中取消連結您的專案。

啟用訊息傳遞資料匯出

具有 FCM SDK 8.6.0 或更高版本的 iOS 裝置可以啟用其應用程式的訊息傳送資料匯出。 FCM 支援警報和後台通知的資料匯出。在啟用這些選項之前，您必須先為您的專案建立 FCM-BiqQuery 鏈接，如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)
  }
}

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。必須對收到的每個通知進行此呼叫：

迅速

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

請注意，針對過時的代幣或不活動的註冊可能會誇大其中一些統計數據。

導出表的schema為：

_PARTITIONTIME	時間戳	此偽列包含載入資料的當天開始的時間戳記（以 UTC 為單位）。對於 YYYYMMDD 分區，此偽列包含值 TIMESTAMP('YYYY-MM-DD')。
事件時間戳	時間戳	伺服器記錄的事件時間戳
項目編號	整數	項目編號標識發送訊息的項目
訊息ID	細繩	訊息ID標識訊息。訊息 ID 由應用程式 ID 和時間戳記生成，在某些情況下可能不是全域唯一的。
實例 ID	細繩	訊息發送到的應用程式的唯一 ID（如果可用）。它可以是實例 ID 或 Firebase 安裝 ID。
訊息類型	細繩	訊息的類型。可以是通知訊息或數據訊息。主題用於識別主題或活動發送的原始訊息；後續訊息是通知訊息或數據訊息。
sdk_平台	細繩	接收者應用程式的平台
應用程式名稱	細繩	Android 應用程式的套件名稱或 iOS 應用程式的捆綁包 ID
折疊鍵	細繩	折疊鍵標識一組可以折疊的訊息。當設備未連接時，只有具有給定折疊鍵的最後一條訊息才會排隊等待最終傳遞
優先事項	整數	訊息的優先順序。有效值為“正常”和“高”。在 iOS 上，這些對應於 APN 優先權 5 和 10
TTL	整數	此參數指定如果設備離線，訊息應在 FCM 儲存中保留多長時間（以秒為單位）
話題	細繩	訊息發送到的主題的名稱（如果適用）
批量 ID	整數	批次 ID 標識一組相關訊息，例如傳送到某個主題的特定訊息
事件	細繩	事件的類型。可能的值為： 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 Key）； INVALID_TTL：由於 TTL 無效，發送訊息的請求被拒絕。
分析標籤	細繩	使用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;