2024년 데모 데이에서 Firebase를 사용하여 AI 기반 앱을 빌드하고 실행하는 방법에 관한 데모를 시청하세요. 지금 시청하세요.

FCM 메시�� 정보

Firebase Cloud Messaging(FCM)은 다양한 메시징 옵션과 기능을 제공합니다. 이 페이지의 정보는 다양한 유형의 FCM 메시지에 관한 이해를 돕고 이를 사용해 구현할 수 있는 기능을 소개하기 위한 내용입니다.

메시지 유형

FCM을 통해 2가지 유형의 메시지를 클라이언트에 보낼 수 있습니다.

알림 메시지: 종종 '표시 메시지'로 간주됩니다. FCM SDK에서 자동으로 처리합니다.
데이터 메시지: 클라이언트 앱에서 처리합니다.

알림 메시지에는 사용자에게 표시되는 키 모음이 사전 정의되어 있습니다. 반면 데이터 메시지에는 사용자가 정의한 커스텀 키-값 쌍만 포함됩니다. 알림 메시지에 데이터 페이로드(선택사항)가 포함될 수 있습니다. 두 메시지 유형의 최대 페이로드는 4,096바이트입니다. Firebase 콘솔에서 메시지를 보내는 경우는 예외로 1,000자(영문 기준)의 글자 수 제한이 적용됩니다.

	사용 시나리오	전송 방법
알림 메시지	클라이언트 앱이 백그라운드에서 실행 중일 때 FCM SDK가 앱을 대신하여 최종 사용자 기기에 메시지를 표시합니다. 그 외의 경우에는 알림이 ��신될 때 앱이 포그라운드에서 실행 중이면 앱의 코드에 따라 동작이 결정됩니다. 알림 메시지에는 사용자에게 표시되는 사전 정의된 키 모음 및 커스텀 키-값 쌍의 데이터 페이로드(선택사항)가 포함됩니다.	Cloud Functions 또는 앱 서버와 같은 신뢰할 수 있는 환경에서 Admin SDK 또는 HTTP v1 API를 사용합니다. `notification` 키를 설정합니다. 선택사항으로 데이터 페이로드를 추가할 수 있습니다. 항상 축소형입니다. 디스플레이 알림의 예시를 보고 요청 페이로드를 전송하세요. 알림 작성기 사용: 메시지 본문, 제목 등을 입력하고 전송합니다. 커스텀 데이터를 제공하여 선택사항인 데이터 페이로드를 추가합니다.
데이터 메시지	클라이언트 앱이 데이터 메시지 처리를 담당합니다. 데이터 메시지에는 예약 키 이름 없이 커스텀 키-값 쌍만 있습니다(아래 참조).	Cloud Functions 또는 앱 서버와 같은 신뢰할 수 있는 환경에서 Admin SDK 또는 FCM 서버 프로토콜을 사용합니다. 전송 요청에서 `data` 키를 설정합니다.

앱이 백그라운드에서 실행 중일 때 FCM SDK가 알림 표시를 자동으로 처리하게 하려면 알림 메시지를 사용하세요. 자체 클라이언트 앱 코드로 메시지를 처리하려면 데이터 메시지를 사용하세요.

FCM은 선택사항인 데이터 페이로드를 포함하는 알림 메시지를 보낼 수 있습니다. 이러한 경우 알림 페이로드 표시는 FCM에서 처리하고 데이터 페이로드는 클라이언트 앱에서 처리합니다.

알림 메시지

테스트, 마케팅, 사용자 재참여 유도를 위해 Firebase 콘솔을 사용하여 알림 메시지를 전송할 수 있습니다. Firebase 콘솔은 애널리틱스 기반의 A/B 테스팅을 제공하여 마케팅 메시지를 수정하고 개선하는 데 도움이 됩니다.

Admin SDK 또는 FCM 프로토콜을 사용하여 프로그래매틱 방식으로 알림 메시지를 보내려면 notification 키를 알림 메시지에서 사용자에게 표시되는 부분에 필요한 사전 정의된 키 옵션 모음으로 설정합니다. 예를 들어 다음은 메신저 앱의 JSON 형식 알림 메시지입니다. 사용자의 기기에 제목이 'Portugal vs. Denmark'이고 본문이 'great match!'인 메시지가 표시됩니다.

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

앱이 백그라운드 상태이면 알림 메시지가 알림 목록으로 전송됩니다. 포그라운드 상태의 앱인 경우 콜백 함수가 메시지를 처리합니다.

알림 메시지를 작성하는 데 사용할 수 있는 사전 정의된 키의 전체 목록은 HTTP v1 프로토콜 알림 객체 참조 문서를 확인하세요.

데이터 메시지

커스텀 키-값 쌍으로 적절한 키를 설정하여 클라이언트 앱으로 데이터 페이로드를 보냅니다.

예를 들어 다음은 위와 동일한 메신저 앱의 JSON 형식 메시지입니다. 정보는 공통 data 키에 캡슐화되어 있고 클라이언트 앱이 콘텐츠를 해석합니다.

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

위의 예시는 최상위 수준 또는 공통 data 필드의 사용법을 보여주며, 메시지를 수신한 모든 플랫폼의 클라이언트가 해석합니다. 각 플랫폼에서 클라이언트 앱이 콜백 함수의 데이터 페이로드를 수신합니다.

데이터 메시지 암호화

Android 전송 레이어(FCM 아키텍처 참조)에서는 지점 간 암호화를 사용합니다. 필요에 따라 데이터 메시지에 엔드 투 엔드 암호화를 추가할 수 있습니다. FCM은 엔드 투 엔드 솔루션을 제공하지 않습니다. Capillary 또는 DTLS와 같은 외부 솔루션을 사용할 수 있습니다.

선택사항인 데이터 페이로드가 포함된 알림 메시지

프로그래매틱 방식으로 또는 Firebase 콘솔을 통해 커스텀 키-값 쌍의 선택적 페이로드를 포함하는 알림 메시지를 보낼 수 있습니다. 알림 작성기에서 고급 옵션의 커스텀 데이터 필드를 사용하세요.

알림과 데이터 페이로드가 모두 포함된 메시지를 수신한 경우의 앱 동작은 앱이 백그라운드 상태인지 아니면 포그라운드 상태인지에 따라 다릅니다. 특히 수신 당시에 앱이 활성 상태였는지 여부에 따라 다릅니다.

백그라운드 상태인 경우 알림 페이로드가 앱의 알림 목록에 수신되며 사용자가 알림을 탭한 경우에만 앱에서 데이터 페이로드를 처리합니다.
포그라운드 상태인 경우 앱에서 페이로드가 둘 다 제공되는 메시지 객체를 수신합니다.

다음은 notification 키와 data 키가 둘 다 포함된 JSON 형식 메시지입니다.

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

여러 플랫폼의 메시지 맞춤설정

Firebase Admin SDK 및 FCM v1 HTTP 프로토콜을 모두 사용하면 메시지 요청을 통해 message 객체에 제공되는 모든 필드를 설정할 수 있습니다. 여기에는 다음이 포함됩니다.

메시지를 수신한 모든 앱 인스턴스에서 해석하는 공통 필드 모음
지정된 플랫폼에서 실행되는 앱 인스턴스에서만 해석되는 AndroidConfig 및 WebpushConfig와 같은 플랫폼별 필드 집합

플랫폼별 블록을 사용하면 수신 시 올바르게 처리할 수 있도록 다양한 플랫폼에 맞게 메시지를 유연하게 맞춤설정할 수 있습니다. FCM 백엔드는 지정된 모든 매개변수를 고려하여 각 플랫폼에 맞게 메시지를 맞춤설정합니다.

공통 필드를 사용해야 하는 경우

다음 작업에 공통 필드를 사용합니다.

Apple, Android, 웹 등 모든 플랫폼의 앱 인스턴스 타겟팅
주제로 메시지 전송

플랫폼에 관계없이 모든 앱 인스턴스가 다음 공통 필드를 해석할 수 있습니다.

플랫폼별 필드를 사용해야 하는 경우

다음 작업을 하려면 플랫폼별 필드를 사용합니다.

특정 플랫폼에만 필드 전송
공통 필드 외에도 플랫폼별 필드 전송

특정 플랫폼에만 값을 보내려면 공통 필드를 사용하지 말고 플랫폼별 필드를 사용하세요. 예를 들어 Android를 제외한 Apple 플랫폼과 웹에만 알림을 보내려면 Apple 및 웹용으로 각각 하나씩 2개의 개별 필드 모음을 사용해야 합니다.

특정 전송 옵션으로 메시지를 보내는 경우에는 플랫폼별 필드를 사용하여 설정합니다. 원하는 경우 플랫폼별로 다른 값을 지정할 수 있지만 여러 플랫폼에 근본적으로 동일한 값을 설정하는 경우에도 플랫폼별 필드를 사용해야 합니다. 그 이유는 각 플랫폼에서 값을 약간씩 다르게 해석할 수 있기 때문입니다. 예를 들어 TTL(수명)이 Android에서는 만료 시간(초 단위)으로 설정되지만 Apple에서는 만료일로 설정됩니다.

예: 플랫폼별 전송 옵션이 있는 알림 메시지

다음 v1 전송 요청은 모든 플랫폼에 공통 알림 제목과 콘텐츠를 보내지만 일부 플랫폼별 재정의도 보냅니다. 이 요청은 특히 다음과 같이 설정합니다.

Android와 웹 플랫폼의 경우 TTL(수명)을 길게 설정하지만 APN(Apple 플랫폼) 메시지 우선순위는 낮게 설정합니다.
사용자가 Android와 Apple의 알림을 탭할 경우의 결과를 정의하기 위해 각각 click_action 및 category의 적절한 키를 설정합니다.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

메시지 본문의 플랫폼별 블록에서 제공하는 키에 관한 자세한 내용은 HTTP v1 참조 문서를 확인하세요. 메시지 본문에 포함되는 보내기 요청 작성에 관한 자세한 내용은 보내기 요청 작성을 참조하세요.

전송 옵션

FCM은 Android 기기로 전송되는 메시지에 특정 전송 옵션 모음을 제공하며 Apple 플랫폼과 웹에도 비슷한 옵션을 허용합니다. 예를 들어 '축소형' 메시지 동작은 Android에서는 FCM의 collapse_key, Apple에서는 apns-collapse-id, 자바스크립트 및 웹에서는 Topic을 통해 지원됩니다. 자세한 내용은 이 섹션의 설명 및 관련 참조 문서를 확인하세요.

비축소형 메시지 및 축소형 메시지

비축소형 메시지란 각각의 개별 메시지가 기기로 전송됨을 의미합니다. 서버에 접속하여 데이터를 가져오기 위해 모바일 앱으로 콘텐츠 없이 '핑'을 보내는 것과 같은 축소형 메시지와는 달리 비축소형 메시지는 유용한 콘텐츠를 전송합니다.

비축소형 메시지의 대표적인 사용 사례는 채팅 메시지나 중요한 메시지입니다. 예를 들어 메신저 앱에서는 메시지마다 콘텐츠가 다르기 때문에 모든 메시지를 전송하게 됩니다.

Android의 경우 축소 없이 저장할 수 있는 메시지는 최대 100개입니다. 이 한도에 도달하면 저장된 메시지가 모두 삭제됩니다. 기기가 다시 온라인 상태가 되면 한도에 도달했음을 나타내는 특수한 메시지를 수신합니다. 그러면 보통 앱에서 앱 서버에 전체 동기화를 요청하는 방식으로 상황을 올바르게 처리할 수 있습니다.

축소형 메시지는 메시지가 아직 기기로 전송되지 않은 경우 새 메시지로 대체될 수 있는 메시지입니다.

축소형 메시지의 일반적인 사용 사례는 모바일 앱에 서버의 데이터와 동기화할 것을 알리는 데 사용되는 메시지입니다. 사용자에게 최신 득점에 대해 업데이트하는 스포츠 앱을 예시로 들 수 있습니다. 이 경우 최근 메시지만 의미가 있습니다.

Android에서 메시지를 축소형으로 표시하��면 메시지 페이로드에 collapse_key 매개변수를 포함합니다. 기본적으로 축소 키는 Firebase 콘솔에 등록된 앱 패키지 이름입니다. FCM 서버는 서로 다른 축소 키를 갖는 축소형 메시지를 기기당 4개씩 동시에 저장할 수 있습니다. 이 한도를 초과하면 FCM에서 축소 키 4개만 보��며 ��한 키가 보존되지는 알 수 없습니다.

페이로드가 없는 주제 메시지는 기본적으로 축소형입니다. 알림 메시지는 항상 축소 가능하며 collapse_key 매개변수를 무시합니다.

어떤 메시지를 사용해야 하나요?

앱에서 비축소형 메시지를 사용할 필요가 없다면 성능 면에 있어서는 축소형 메시지를 선택하는 것이 좋습니다. 하지만 축소형 메시지를 사용하는 경우에는 FCM이 지정한 기간에 FCM에서 사용할 수 있는 다른 축소 키를 등록 토큰당 최대 4개만 허용한다는 점을 기억하세요. 이 한도를 초과하면 예측할 수 없는 결과가 발생할 수 있으므로 초과해서는 안 됩니다.

	사용 시나리오	전송 방법
비축소형	모든 메시지가 클라이언트 앱에서 중요하므로 모두 전송되어야 합니다.	알림 메시지를 제외한 모든 메시지가 기본적으로 비축소형입니다.
축소형	클라이언트 앱과 관련이 없는 이전 관련 메시지를 렌더링하는 새로운 메시지가 있으면 FCM이 이전 메시지를 대체합니다. 서버에서 데이터 동기화를 시작하는 데 사용되는 메시지 또는 기한이 지난 알림 메시지를 예시로 들 수 있습니다.	메시지 요청에 적절한 매개변수를 설정합니다. Android: `collapseKey` Apple: `apns-collapse-id` 웹: `Topic` 기존 프로토콜(모든 플랫폼): `collapse_key`

메시지 우선순위 설정

다운스트림 메시지의 전송 우선순위(보통 및 높은 우선순위)를 할당할 수 있는 옵션 두 개가 있습니다. 이 동작은 플랫폼에 따라 조금씩 다르지만, 보통 및 높은 우선순위 메시지 전송이 작동하는 방식은 다음과 같습니다.

보통 우선순위: 보통 우선순위 메시지는 앱이 포그라운드 상태이면 즉시 전송됩니다. 백그라운드 앱의 경우 전송이 지연될 수 있습니다. 새로운 이메일 알림, UI 동기화 유지, 백그라운드 앱 데이터 동기화와 같이 시간이 크게 중요하지 않은 메시지의 경우 보통 전송 우선순위를 선택하세요.
높은 우선순위: FCM이 기기가 잠자기 모드인 경우에도 높은 우선순위 메시지를 즉시 전송하려고 시도합니다. 높은 우선순위 메시지는 사용자에게 표시되는 시간에 민감한 콘텐츠를 위한 것입니다.

Apple 기기로 데이터 메시지를 전송할 때 우선순위를 5 또는 보통 우선순위로 설정해야 합니다. 높은 우선순위로 전송된 메시지는 FCM백엔드에서 INVALID_ARGUMENT 오류와 함께 거부됩니다.

다음은 잡지 구독자에게 새 콘텐츠를 다운로드할 수 있다고 알리기 위해 FCM HTTP v1 프로토콜을 통해 보내는 보통 우선순위 메시지의 예시입니다.

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

메시지 우선순위 설정에 관한 플랫폼별 세부정보는 다음을 참조하세요.

생명에 중요한 사용 사례

FCM API는 긴급 재난 문자 또는 API 사용 또는 실패가 사망, 상해 또는 환경적 피해(예: 원자력 시설, 항공 교통 통제 또는 생명 유지 시스템)를 야기할 수 있는 기타 고위험 활동을 위해 고안되지 않았습니다. 이러한 사용은 서비스 약관 섹션 4. a. 7에서 명시적으로 금지하고 있습니다. 앱의 약관 준수를 관리하고 미준수로 인해 발생하는 피해에 대한 책임은 전적으로 귀하에게 있습니다. Google은 API를 '있는 그대로' 제공하며, 귀하 또는 귀하의 사용자에 대한 책임이나 기타 의무 없이 언제든지 어떤 이유로든 API 또는 그 일부나 기능 또는 이에 대한 액세스를 중단할 권리를 보유합니다.

메시지 수명 설정

메시지를 보내면 보통 FCM에서 바로 전송됩니다. 하지만 바로 전송하는 것이 불가능한 경우도 있습니다. 예를 들어 플랫폼이 Android인 경우 기기가 꺼져 있거나 오프라인이거나 기타 사용 불가능한 상태일 수 있습니다. 또는 FCM에서 앱이 과도한 리소스를 소비하여 배터리 수명이 부정적인 영향을 받지 않도록 의도적으로 메시지를 지연할 수 있습니다.

이러한 상황이 발생하면 FCM에서 메시지를 저장한 후 전송할 수 있게 되면 바로 전송합니다. 대부분의 경우 문제가 없지만 일부 앱은 지연된 메시지가 전혀 전송되지 않습니다. 예를 들어 메시지가 수신 전화나 영상 채팅 알림인 경우 호출이 종료되기 이전의 짧은 시간 동안만 메시지가 의미 있습니다. 또는 메시지가 이벤트 초대인 경우 이벤트가 종료된 후에 수신되면 의미가 없습니다.

Android, 웹, 자바스크립트에서는 메시지의 최대 수명을 지정할 수 있습니다. 값의 길이가 0초에서 2,419,200초(28일) 사이여야 하며 FCM이 메시지를 저장하여 전송 시도하는 최대 기간에 해당합니다. 이 필드가 포함되지 않은 요청은 최대 기간인 4주가 기본값입니다.

다음은 이 기능을 사용할 수 있는 몇 가지 예입니다.

영상 채팅 수신 전화
만료일이 있는 초대 이벤트
캘린더 일정

메시지 수명을 지정할 경우의 또 다른 장점은 FCM에서 TTL(수명) 값이 0초인 메시지에 축소형 메시지 제한을 적용하지 않는다는 점입니다. FCM은 '지금 즉시 전성되거나 절대 전송되어서는 안 되는' 메시지 처리에 최선을 다합니다. time_to_live 값이 0이면 즉시 전송할 수 없는 메시지는 삭제된다는 점에 유의하세요. 그러나 이러한 메시지는 저장되지 않으므로 알림 메시지를 보낼 때 지연 시간이 최소화됩니다.

다음은 TTL이 포함된 요청의 예시입니다.

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

메시지의 수명

앱 서버가 FCM에 메시지를 게시한 후 메시지 ID를 다시 수신했다고 해서 메시지가 이미 기기로 전송되었다는 의미는 아닙니다. 더 정확히 말하면 전송이 수락되었다는 의미입니다. 메시지가 수락된 후 수행되는 작업은 여러 요인에 따라 달라집니다.

최적의 상황에서는 기기가 FCM에 연결된 경우 화면이 켜져 있고 아무런 제한사항이 없으면 메시지가 즉시 전송됩니다.

기기가 연결되어 있지만 잠자기 상태인 경우 FCM은 기기에서 잠자기 상태가 해제될 때까지 우선순위가 낮은 메시지를 저장합니다. 또한 이 시점에서 collapse_key 플래그가 역할을 수행합니다. 축소 키와 등록 토큰이 동일한 메시지가 이미 저장되어 전송 대기 중이라면 이전 메시지가 삭제되고 새 메시지로 대체됩니다. 즉, 이전 메시지가 새 메시지에 의해 축소됩니다. 하지만 축소 키가 설정되어 있지 않으면 나중에 전송할 수 있도록 새 메시지와 이전 메시지 모두 저장됩니다.

기기가 FCM에 연결되어 있지 않으면 연결이 설정될 때까지 축소 키 규칙을 반영하여 메시지가 저장됩니다. 연결이 설정되면 FCM이 대기 중인 모든 메시지를 기기로 전송합니다. 예를 들어 기기가 공장 재설정 상태로 초기화되는 등의 사유로 다시 연결되지 않으면 결국 메시지 제한 시간이 초과되어 FCM 스토리지에서 삭제됩니다. time_to_live 플래그가 설정되지 않은 한 기본 제한 시간은 4주입니다.

메시지 전송에 대한 자세한 정보

Android 또는 Apple 플랫폼에서의 메시지 전송에 대한 자세한 정보는 Apple 및 Android 기기에서 열린 전송 메시지 수와 Android 앱의 '노출수'(사용자에게 표시된 알림) 데이터가 기록된 FCM 보고 대시보드를 확인합니다.

직접 채널 메시징이 사용하도록 설정된 Android 기기에서는 기기가 FCM에 연결되지 않은 시간이 1개월을 초과하면 FCM은 여전히 메시지를 수신하지만 메시지를 즉시 삭제합니다. 데이터 메시지를 마지막으로 보낸 지 4주가 지나기 전에 기기가 연결되면 클라이언트가 onDeletedMessages() 콜백을 수신합니다. 그러면 보통 앱에서 앱 서버에 전체 동기화를 요청하는 방식으로 상황을 올바르게 처리할 수 있습니다.

마지막으로 FCM에서 기기로 메시지를 전송하려고 했지만 앱이 제거된 경우 FCM이 메시지를 즉시 삭제하고 등록 토큰을 무효화합니다. 이후 이 기기로 메시지를 보내려고 시도하면 NotRegistered 오류가 발생합니다.

제한 및 할당량

FCM을 통해 보낸 모든 메시지를 항상 전송하는 것을 목표로 하고 있지만 모든 메시지를 전송하면 전반적인 사용자 환경의 성능이 저하되는 경우도 있습니다. 그 밖에 FCM이 모든 발신자에게 확장 가능한 서비스를 제공하도록 범위를 지정해야 하는 경우도 있습니다. 다음 섹션에 설명된 한도 및 할당량의 유형은 이러한 중요한 요인의 균형을 맞추는 데 도움이 됩니다.

다운스트림 메시지 제한

HTTP v1 API는 다운스트림 메시지에 프로젝트별 분당 할당량을 도입했습니다. 분당 60만 개의 메시지라는 기본 할당량은 시스템의 안정성을 보호하고 급증하는 프로젝트의 영향을 최소화하면서 FCM 개발자의 99% 이상을 지원합니다.

급증하는 트래픽 패턴으로 인해 할당량 초과 오류가 발생할 수 있습니다. 할당량 초과 시나리오에서는 다음 분에 할당량이 다시 채워질 때까지 시스템에서 HTTP 상태 코드 429(QUOTA_EXCEEDED)를 제공합니다. 과부하 상황에서도 429 응답이 반환될 수 있으므로 게시된 권장사항에 따라 429를 처리하는 것이 좋습니다.

다음 사항을 참고하세요.

다운스트림 할당량은 요청이 아닌 메시지를 측정합니다.
클라이언트 오류(HTTP 상태 코드 400~499)가 계산됩니다(429 제외).
할당량은 분 단위로 ��용되지만 이러한 시간(분)은 시계 기준으로 계산되지 않습니다.

할당량 모니터링

Google Cloud 콘솔에서 할당량, 사용량, 오류를 확인할 수 있습니다.

Google Cloud 콘솔로 이동
API 및 서비스를 선택합니다.
표 목록에서 Firebase Cloud Messaging API를 선택합니다.
할당량 및 시스템 한도를 선택합니다.

참고: 이 그래프는 할당량 분과 정확하게 시간 정렬되지 않으므로 트래픽이 할당량 미만으로 보일 때 429가 제공될 수 있습니다.

할당량 상향 요청

할당량 상향을 요청하기 전에 다음 사항을 확인하세요.

사용량이 연속 5분 이상 할당량의 80% 이상입니다.
특히 트래픽이 급증할 때 클라이언트 오류율 5% 미만입니다.
대규모 메시지 전송 권장사항을 준수합니다.

이 기준을 충족하는 경우 최대 25%까지 할당량 상향 요청을 제출할 수 있으며 FCM에서는 요청을 처리하기 위해 모든 실질적인 노력을 기울입니다(할당량 상향은 보장되지 않음).

임박한 출시 또는 임시 이벤트로 인해 더 많은 다운스트림 메시징 할당량이 필요한 경우, 최소 15일 전에 할당량을 요청하여 요청을 처리할 수 있는 충분한 시간을 확보해야 합니다. 대규모 요청(분당 메시지 1,800만 개 이상)의 경우 최소 30일 이전에 통지해야 합니다. 출시 및 특별 이벤트 요청에도 클라이언트 오류율 및 권장사항 요구사항이 계속 적용됩니다.

FCM 할당량에 관한 FAQ도 참조하세요.

주제 메시지 한도

주제 구독 추가/삭제 속도는 프로젝트당 3,000QPS로 제한됩니다.

메시지 전송 속도는 팬아웃 제한을 참조하세요.

팬아웃 제한

메시지 팬아웃이란 주제 및 그룹을 타겟팅하거나 알림 작성기를 사용하여 잠재고객 및 사용자 세그먼트를 타겟팅하는 경우와 같이 여러 기기로 메시지를 전송하는 프로세스입니다.

메시지 팬아웃은 즉각적인 프로세스가 아니므로 경우에 따라 여러 개의 팬아웃을 동시에 진행하는 것이 가능합니다. 프로젝트당 동시 메시지 팬아웃 수는 1,000개로 제한되며, 제한 수에 도달하면 일부 진행 중인 팬아웃이 완료될 때까지 추가 팬아웃 요청이 거부되거나 팬아웃 요청이 지연될 수 있습니다.

실제 가능한 팬아웃 속도는 동시에 팬아웃을 요청하는 프로젝트 수의 영향을 받습니다. 개별 프로젝트의 팬아웃 속도 10,000QPS는 드물지 않지만 이 속도는 보장되지 않으며 시스템 전체 부하에 따라 달라집니다. 사용 가능한 팬아웃 용량은 팬아웃 요청이 아닌 프로젝트 간에 분할됩니다. 따라서 프로젝트에 진행 중인 팬아웃이 두 개 있으면 각 팬아웃 속도는 사용 가능한 팬아웃 속도의 절반이 됩니다. 따라서 팬아웃 속도를 최대화하려면 활성 팬아웃을 한 번에 ��나만 진행하는 것이 가장 좋습니다.

축소형 메시지 제한

위에서 설명한 대로 축소형 메시지는 서로 겹쳐서 축소되도록 설계되었으며, 콘텐츠가 없는 알림입니다. 개발자가 앱에 동일한 메시지를 너무 자주 반복하는 경우에는 사용자 배터리에 미치는 영향을 줄이기 위해 메시지 전송을 지연(제한)합니다.

예를 들어 기기 하나에 새 이메일 동기화 요청을 많이 보내는 경우 기기가 더 낮은 평균 속도로 동기화할 수 있도록 다음 이메일 동기화 요청이 몇 분 지연될 수 있습니다. 이 제한은 사용자가 느끼는 배터리 영향을 제한하기 위한 목적으로만 수행됩니다.

높은 버스트 전송 패턴이 필요한 경우에는 비축소형 메시지를 선택하는 것이 좋습니다. 이러한 메시지의 경우 배터리 소모를 줄이기 위해 메시지에 콘텐츠를 포함시켜야 합니다.

축소형 메시지를 기기 하나당 앱별로 메시지 20개로 제한하고 3분마다 메시지 1개를 다시 채웁니다.

XMPP 서버 제한

FCM XMPP 서버에 연결할 수 있는 속도를 프로젝트당 1분에 400개의 연결로 제한합니다. 메시지 전송에 지장을 주지 않지만 시스템의 안정성을 확보하는 것이 중요합니다. 프로젝트마다 FCM에서 동시 연결 2,500개를 허용합니다.

XMPP를 사용한 업스트림 메시징의 경우 FCM에서 업스트림 메시지를 프로젝트별 분당 1,500,000개로 제한하여 업스트림 대상 서버에 과부하가 걸리지 않도록 합니다.

악성 앱 동작으로 인한 배터리 방전을 방지하기 위해 기기당 업스트림 메시지를 1,000/분으로 제한합니다.

단일 기기에 대한 최대 메시지 속도

Android의 경우 단일 기기에 메시지를 분당 최대 240개, 시간당 5,000개 전송할 수 있습니다. 이렇게 임곗값이 높은 이유는 사용자가 채팅에서 빠르게 상호작용할 때와 같이 단기간에 트래픽이 급증하도록 허용하기 위해서입니다. 이 한도는 전송 로직 오류로 인해 의도치 않게 기기의 배터리가 방전되는 것을 방지합니다.

iOS에서는 비율이 APN 한도를 초과하면 오류가 반환됩니다.

FCM 포트 및 방화벽

조직에 인터넷 트래픽 송수신을 제한하는 방화벽이 있으면 모바일 기기에서 FCM을 사용하여 연결할 수 있도록 ��화벽을 구성해야 네트워크의 기기에서 메시지를 수신할 수 있습니다. FCM은 대개 포트 5228을 사용하지만 443, 5229, 5230을 사용하는 경우도 있습니다.

네트워크에 연결된 기기의 경우 IP 범위가 매우 자주 변경되며 개발자의 방화벽 규칙이 오래되면 사용자 환경에 영향을 줄 수 있으므로 FCM에서 특정 IP를 제공하지 않습니다. IP 제한 없이 포트 5228~5230, 443을 허용하는 것이 가장 좋습니다. 하지만 IP 제한이 있어야 한다면 goog.json에 나와 있는 모든 IP 주소를 허용해야 합니다. 이 긴 목록은 정기적으로 업데이트되며 규칙을 월 단위로 업데이트하는 것이 좋습니다. 방화벽 IP 제한으로 인해 발생하는 문제는 보통 간헐적이며 진단하기 어렵습니다.

Google에서는 IP 주소 대신 허용 목록에 포함될 수 있는 도메인 이름 집��을 제공합니다. 이러한 호스트 이름은 아래에 나와 있습니다. 추가 호스트 이름을 사용하기 시작하면 여기에 목록이 업데이트됩니다. 방화벽 규칙에 도메인 이름을 사용하면 방화벽 기기에서 작동하거나 작동하지 않을 수 있습니다.

열려는 TCP 포트:

5228
5229
5230
443

열릴 호스트 이름:

mtalk.google.com
mtalk4.google.com
mtalk-staging.google.com
mtalk-dev.google.com
alt1-mtalk.google.com
alt2-mtalk.google.com
alt3-mtalk.google.com
alt4-mtalk.google.com
alt5-mtalk.google.com
alt6-mtalk.google.com
alt7-mtalk.google.com
alt8-mtalk.google.com
android.apis.google.com
device-provisioning.googleapis.com
firebaseinstallations.googleapis.com

네트워크 주소 변환 및 스테이트풀(Stateful) 패킷 검사 방화벽:

네트워크에서 네트워크 주소 변환(NAT)이나 상태 추적 패킷 검사(SPI)를 구현하는 경우 포트 5228~5230을 통한 연결에 대해 30분 이상의 제한 시간을 구현하세요. 이렇게 하면 Google에서 사용자 휴대기기의 배터리 소비를 줄이면서 안정적인 연결을 제공할 수 있습니다.

VPN 상호작용 및 우회 가능성

Firebase Cloud Messaging은 휴대전화에서 서버로의 푸시 메시지 연결이 안정적이고 최대한 자주 사용할 수 있도록 다양한 조치를 취합니다. VPN을 사용하면 이 작업이 복잡해집니다.

VPN은 FCM에서 안정성과 배터리 수명 극대화를 위해 연결을 조정하는 데 필요한 기본 정보를 마스킹합니다. 경우에 따라 VPN이 활성 상태로 오래 지속된 연결을 끊어 메시지 누락, 메시지 지연, 배터리 사용량 증가 등으로 인한 사용자 환경 악화를 초래할 수 있습니다. VPN이 이를 허용하도록 구성된 경우 암호화된 연결(기본 네트워크 Wi-Fi 또는 LTE)로 VPN을 우회하여 더욱 안정적이고 배터리 사용량이 크지 않은 환경을 보장할 수 있습니다. FCM의 우회 가능한 VPN 사용은 FCM 푸시 알림 채널에 ��라 다릅니다. 등록 트래픽과 같은 기타 FCM 트래픽은 VPN이 활성 상태인 경우 VPN을 사용합니다. FCM 연결이 VPN을 우회하면 IP 마스킹 등 VPN이 제공할 수 있는 추가적인 이점을 잃게 됩니다.

VPN에 따라 우회 가능 여부를 제어하는 방법이 다릅니다. 자세한 내용은 특정 VPN의 문서를 참조하세요.

VPN을 우회할 수 있도록 구성하지 않으면 Firebase Cloud Messaging에서 VPN 네트워크를 사용하여 서버에 연결합니다. 이로 인해 메시지가 지연되는 기간이 발생할 수 있으며 Cloud Messaging이 VPN 연결을 통해 연결을 유지하기 위해 작동하므로 배터리 사용량이 늘어날 수 있습니다.

사용자 인증 정보

구현한 FCM 기능에 따라 다음과 같은 Firebase 프로젝트의 사용자 인증 정보가 필요할 수도 있습니다.

프로젝트 ID	Firebase 프로젝트의 고유 식별자로서 FCM v1 HTTP 엔드포인트에 관한 요청에 사용됩니다. 이 값은 Firebase Console 설정 창에서 확인할 수 있습니다.
등록 토큰	각 클라이언트 앱 인스턴스를 식별하는 고유한 토큰 문자열입니다. 단일 기기 및 기기 그룹 메시징에 등록 토큰이 필요합니다. 등록 토큰은 비밀로 유지되어야 한다는 점에 유의하세요.
발신자 ID	Firebase 프로젝트를 만들 때 생성되는 고유한 숫자 값으로서 Firebase 콘솔 설정 창의 Cloud Messaging 탭에서 확인할 수 있습니다. 발신자 ID는 클라이언트 앱에 메시지를 보낼 수 있는 각 발신자를 식별하는 데 사용됩니다.
액세스 토큰	HTTP v1 API에 대한 요청을 승인하는 단기 OAuth 2.0 토큰입니다. 이 토큰이 Firebase 프로젝트에 속한 서비스 계정에 연결됩니다. 액세스 토큰을 만들고 순환하려면 보내기 요청 승인에 설명된 단계를 따르세요.
서버 키(지원 중단된 기존 프로토콜용)	앱 서버가 지원 중단된 Firebase Cloud Messaging 기존 프로토콜을 통한 메시지 전송과 같은 Google 서비스에 액세스할 수 있도록 인증하는 서버 키입니다. 중요: 클라이언트 코드에 서버 키를 포함하지 마세요. 또한 앱 서버를 인증할 때 서버 키만 사용해야 합니다. Android, Apple 플랫폼, 브라우저 키는 FCM에서 거부합니다.