메시지 전송 이해

FCM은 메시지 전송에 관한 통계를 확인할 수 있는 세 가지 도구를 제공합니다.

• Firebase Console 메시지 전송 보고서
• Firebase 클라우드 메시징 Data API에서 집계된 Android SDK 전송 측정항목
• Google BigQuery로 종합적인 데이터 내보내기

이 페이지에서 설명하는 모든 보고 도구는 Google 애널리틱스를 필요로 합니다. 프로젝트에서 Google 애널리틱스를 사용 설정하지 않은 경우 Firebase 프로젝트 설정의 통합 탭에서 설정할 수 있습니다.

이 페이지에서 다루고 있는 다양한 통계 자료를 보고하는 경우 애널리틱스 데이터 일괄 처리로 인한 최대 24시간의 지연 가능성이 있습니다.

메시지 전송 보고서

Firebase Console의 보고서 탭에서는 알림 작성기 및 FCM API를 통해 전송된 메시지를 비롯하여 Android나 Apple 플랫폼 FCM SDK에 전송된 메시지에 대해 다음과 같은 데이터를 확인할 수 있습니다.

• 전송 — 데이터 메시지 또는 알림 메시지가 전송을 위해 대기열에 추가되었거나 전송을 위해 APN과 같은 서드파티 서비스에 성공적으로 전달되었습니다. 자세한 내용은 메시지의 수명을 참조하세요.
• 수신됨(Android 기기에만 제공) — 데이터 메시지 또는 알림 메시지가 앱에 수신되었습니다. 이 데이터는 수신 Android 기기에 FCM SDK 18.0.1 이상이 설치된 경우에 사용할 수 있습니다.
• 노출(Android 기기의 알림 메시지에만 제공) — 앱이 백그라운드 상태일 때 디스플레이 알림이 기기에 표시되었습니다.
• 확인 — 사용자가 알림 메시지를 확인했습니다. 앱이 백그라운드 상태일 때 수신된 알림만 보고됩니다.

이 데이터는 알림 페이로드가 포함된 모든 메시지 및 라벨이 지정된 모든 데이터 메시지에 제공됩니다. 라벨을 자세히 알아보려면 메시지에 애널리틱스 라벨 추가를 참조하세요.

메시지 보고서를 확인할 때 표시되는 데이터의 기간은 CSV로 내보내기 옵션을 통해 설정할 수 있습니다. 또한 다음 기준으로 필터링할 수 있습니다.

• 플랫폼(iOS 또는 Android)
• 앱
• 커스텀 애널리틱스 라벨

메시지에 애널리틱스 라벨 추가

메시지에 라벨을 지정하면 라벨 또는 라벨 세트로 전송 통계를 필터링할 수 있으므로 커스텀 분석에 매우 유용합니다. 메시지 객체의 fcmOptions.analyticsLabel 필드나 플랫폼별 AndroidFcmOptions 또는 ApnsFcmOptions 필드를 설정하여 HTTP v1 API를 통해 전송된 모든 메시지에 라벨을 추가할 수 있습니다.

애널리틱스 라벨은 ^[a-zA-Z0-9-_.~%]{1,50}$ 형식의 텍스트 문자열입니다. 라벨에는 소문자, 대문자, 숫자, 다음 기호를 포함할 수 있습니다.

• -
• ~
• %

최대 길이는 50자(영문 기준)입니다. 일일 최대 100개의 고유 라벨을 지정할 수 있으며 이 한도를 초과한 라벨이 있는 메시지는 보고되지 않습니다.

Firebase Console 메시지 보고서 탭에서 모든 기존 라벨 목록을 검색한 후 라벨 1개를 단독으로 사용하거나 라벨을 조합하여 표시되는 통계를 필터링할 수 있습니다.

FCM Data API를 통해 집계된 전송 데이터

Firebase 클라우드 메시징 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%가 아닙니다.

수신된 메시지 수

데이터 세트에는 Android 기기로의 전송을 위해 FCM에서 수신된 메시지 수 집계만 포함되어 있습니다. 모든 비율에서 이 값을 분모로 사용합니다. 기기에서 사용 및 진단 정보 수집을 사용 중지한 사용자를 타겟팅하는 메시지는 이 수에 포함되지 않습니다.

메시지 결과 비율

MessageOutcomePercents 객체에 포함된 필드는 메시지 요청 결과에 대한 정보를 제공합니다. 카테고리는 모두 상호 배타적입니다. 이 측정항목을 통해 '메시지가 전송되나요?' 또는 '메시지가 삭제되는 이유는 무엇인가요?'와 같은 질문에 답할 수 있습니다.

예를 들어 droppedTooManyPendingMessages 필드의 값이 높다면 앱 인스턴스가 수신하는 비축소형 메시지 수가 FCM의 대기 중인 메시지 수 한도인 100개를 초과한다는 신호일 수 있습니다. 메시지 수 한도 초과 방지를 위해서는 앱에서 onDeletedMessages 호출을 처리할 수 있는지 확인하고 축소형 메시지를 전송하는 것이 좋습니다. 마찬가지로 droppedDeviceInactive 비율이 높으면 서버의 등록 토큰을 업데이트하여 비활성 토큰을 삭제하고 주제에서 구독을 취소하라는 신호일 수 있습니다. 관련 권장사항은 FCM 등록 토큰 관리를 참조하세요.

전송 성능 비율

DeliveryPerformancePercents 객체의 필드는 성공적으로 전송 완료된 메시지에 대한 정보를 제공합니다. 이 측정항목을 통해 '메시지가 지연되었나요?' 또는 '메시지가 지연된 이유는 무엇인가요?'와 같은 질문에 답할 수 있습니다. 예를 들어 delayedMessageThrottled의 값이 높으면 기기별 최대 한도를 확실히 초과한 것이므로 메시지 전송 속도를 조정해야 합니다.

메시지 통계 비율

이 객체는 모든 메시지 전송에 대한 추가 정보를 제공합니다. priorityLowered 필드는 우선순위가 HIGH에서 NORMAL로 낮아진 수신된 메시지의 비율을 나타냅니다. 이 값이 높으면 우선순위가 높은 메시지를 적게 전송하거나 우선순위가 높은 메시지가 전송될 때 항상 알림을 표시하도록 하세요. 자세한 내용은 메시지 우선순위에 관한 문서를 참조하세요.

이 데이터는 BigQuery로 내보낸 데이터와 어떻게 다른가요?

BigQuery 내보내기는 FCM 백엔드의 메시지 수신 및 기기의 SDK에서 메시지 전송(FCM 아키텍처의 2단계 및 4단계)에 대한 개별 메시지 로그를 제공합니다. 이 데이터는 개별 메시지가 수신 및 전송 완료되었는지 확인하는 데 도움이 됩니다. 다음 섹션에서 BigQuery 데이터 내보내기에 대해 자세히 알아보세요.

반면에 Firebase 클라우드 메시징 Data API는 특히 Android 전송 레이어(또는 FCM 아키텍처의 3단계)에서 어떤 상황이 발생하는지에 관해 집계된 세부정보를 제공합니다. 이 데이터는 특히 FCM 백엔드에서 Android SDK로의 메시지 전달에 관한 유용한 정보를 제공하며 전송 중에 메시지가 지연되거나 삭제된 이유에 대한 트렌드를 표시하는 데 특히 도움이 됩니다.

경우에 따라 다음과 같은 이유로 두 데이터 세트가 정확하게 일치하지 않을 수 있습니다.

• 집계된 측정항목이 전체 메시지의 일부만 샘플링함
• 집계된 측정항목이 반올림됨
• 공개 기준에 미치지 못하는 측정항목은 표시되지 않음
• Google에서 대량의 트래픽을 관리하는 방법을 최적화하여 일부 메시지 결과가 누락됨

API 제한사항

데이터 타임라인 집계

API는 7일 분량의 과거 데이터를 반환합니다. 그러나 이 API에서 반환하는 데이터는 최대 5일까지 지연될 수 있습니다. 예를 들어 1월 20일에는 1월 9일부터 1월 15일까지의 데이터를 사용할 수 있지만 1월 16일 이후의 데이터는 사용할 수 없습니다. 또한 데이터는 최선의 방식으로 제공됩니다. 데이터 중단이 발생할 경우 FCM은 문제가 해결될 때까지 계속 작동하며 문제가 해결된 후에 데이터를 백필하지 않습니다. 더 큰 규모의 중단이 발생하면 일주일 이상 데이터를 사용할 수 없습니다.

데이터 일치 범위

Firebase 클라우드 메시징 Data API에서 제공하는 측정항목은 메시지 전송의 광범위한 트렌드를 제공하기 위한 것입니다. 그러나 모든 메시지 시나리오의 100%를 제공하지는 않습니다. 다음 시나리오는 측정항목에 반영되지 않는 것으로 알려진 결과입니다.

축소된 메시지

다른 메시지로 축소된 메시지는 데이터 세트에 나타나지 않습니다.

비활성 기기로 전송된 메시지

비활성 기기로 전송된 메시지는 사용하는 데이터 경로에 따라 데이터 세트에 표시될 수도 있고 표시되지 않을 수도 있습니다. 이로 인해 droppedDeviceInactive 및 pending 필드에 오차가 발생할 수 있습니다.

특정 사용자 환경설정의 기기로 전송된 메시지

기기에서 사용 및 진단 정보 수집을 사용 중지한 사용자는 해당 환경설정에 따라 메시지가 집계에 포함되지 않습니다.

반올림 및 최솟값

FCM은 볼륨이 충분히 크지 않은 수는 의도적으로 반올림하고 제외합니다.

BigQuery 데이터 내보내기

BigQuery로 메시지 데이터를 내보내서 추가 분석을 할 수 있습니다. BigQuery를 사용하면 BigQuery SQL로 데이터를 분석하여 다른 클라우드 제공업체로 내보내거나, 커스텀 ML 모델에 데이터를 사용할 수 있습니다. BigQuery로 내보내기에는 메시지 유형 또는 메시지가 API나 알림 작성기를 통해 전송되는지 여부에 관계없이 메시지의 모든 데이터가 포함됩니다.

다음 FCM SDK 최소 버전을 사용하는 기기로 전송된 메시지의 경우 앱의 메시지 전송 데이터 내보내기를 사용 설정할 수 있는 추가 옵션이 있습니다.

• Android 20.1.0 이상
• iOS 8.6.0 이상
• Firebase 웹 SDK 9.0.0 이상

Android 및 iOS의 데이터 내보내기 사용 설정에 대한 자세한 내용은 아래를 참조하세요.

시작하려면 프로젝트를 BigQuery에 연결하세요.

1. 다음 옵션 중 하나를 선택합니다.

   • 알림 작성기를 열고 페이지 하단의 BigQuery 액세스를 클릭합니다.

   • Firebase Console의 통합 페이지에서 BigQuery 카드에 있는 연결을 클릭합니다.

     이 페이지에는 프로젝트 내 모든 FCM 지원 앱의 FCM 내보내기 옵션이 표시됩니다.

2. 화면의 안내에 따라 BigQuery를 사용 설정합니다.

자세한 내용은 Firebase를 BigQuery에 연결을 참조하세요.

클라우드 메시징에 BigQuery 내보내기를 사용 설정한 경우 다음 안내를 따르세요.

• Firebase에서 BigQuery에 데이터를 내보냅니다. 내보내기용 데이터의 초기 전파를 완료하는 데 최대 48시간이 걸릴 수 있습니다.

  • 최대 지난 30일 동안의 데이터 백필을 수동으로 예약할 수도 있습니다.

• 데이터 세트를 만든 후에는 위치를 변경할 수 없지만 데이터 세트를 다른 위치에 복사하거나 다른 위치에서 데이터 세트를 수동으로 이동(다시 만들기)할 수 있습니다. 자세한 내용은 데이터 세트 위치 변경을 참조하세요.

• Firebase에서 Firebase 프로젝트와 BigQuery 간의 정기적인 데이터 동기화를 설정합니다. 이러한 일일 내보내기 작업은 태평양 표준시 기준 오전 4시에 시작되고 일반적으로 24시간 내에 완료됩니다.

• 기본적으로 프로젝트에 있는 모든 앱은 BigQuery에 연결되며 나중에 프로젝트에 추가한 앱은 BigQuery에 자동으로 연결됩니다. 데이터를 전송하는 앱을 별도로 관리할 수 있습니다.

BigQuery 내보내기를 중지하려면 Firebase Console에서 프로젝트를 연결 해제합니다.

메시지 전송 데이터 내보내기 사용 설정

FCM SDK 8.6.0 이상을 사용하는 iOS 기기에서 앱의 메시지 전송 데이터 내보내기를 사용 설정할 수 있습니다. FCM은 알림과 백그라운드 알림의 데이터 내보내기를 지원합니다. 이 옵션을 사용 설정하기 전에 먼저 BigQuery 데이터 내보내기의 설명에 따라 프로젝트의 FCM과 BigQuery 간 연결을 만들어야 합니다.

알림의 전송 데이터 내보내기 사용 설정

알림만 알림 서비스 앱 확장 프로그램을 트리거할 수 있으므로 앱에 알림 서비스 확장 프로그램을 추가하고 서비스 확장 프로그램 내에서 이 API를 호출하여 표시 메시지 추적을 사용 설정해야 합니다. Modifying Content in Newly Delivered Notifications(새로 전송된 알림에서 콘텐츠 수정)에 관한 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로 내보내나요?

비활성 토큰 또는 비활성 등록을 타겟팅하면 통계가 실제보다 높게 나올 수 있습니다.

내보낸 테이블의 스키마는 다음과 같습니다.

내보낸 데이터로 무엇을 할 수 있나요?

다음 섹션에는 내보낸 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 != ''를 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;