FCM 메시지 정보

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

메시지 유형

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

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

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

사용 시나리오 전송 방법
알림 메시지 클라이언트 앱이 백그라운드에서 실행 중일 때 FCM SDK가 앱을 대신하여 최종 사용자 기기에 메시지를 표시합니다. 그 외의 경우에는 알림이 수신될 때 앱이 포그라운드에서 실행 중이면 앱의 코드에 따라 동작이 결정됩니다. 알림 메시지에는 사용자에게 표시되는 사전 정의된 키 모음 및 맞춤 키-값 쌍의 데이터 페이로드(선택사항)가 포함됩니다.
  1. Cloud Functions 또는 앱 서버와 같은 신뢰할 수 있는 환경에서 Admin SDK 또는 FCM 서버 프로토콜을 사용하여 notification 키를 설정합니다. 선택사항으로 데이터 페이로드를 추가할 수 있습니다. 항상 축소형입니다.

    디스플레이 알림의 예시를 보고 요청 페이로드를 전송하세요.

  2. 알림 작성기 사용: 메시지 본문, 제목 등을 입력하고 전송합니다. 커스텀 데이터를 제공하여 선택사항인 데이터 페이로드를 추가합니다.
데이터 메시지 클라이언트 앱이 데이터 메시지 처리를 담당합니다. 데이터 메시지에는 예약 키 이름 없이 커스텀 키-값 쌍만 있습니다(아래 참조). Cloud Functions 또는 앱 서버와 같은 신뢰할 수 있는 환경에서 Admin SDK 또는 FCM 서버 프로토콜을 사용하여 data 키만 설정합니다.

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

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

알림 메시지

테스트, 마케팅, 사용자 재참여 유도를 위해 Firebase 콘솔을 사용하여 알림 메시지를 전송할 수 있습니다. Firebase Console은 애널리틱스 기반의 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!"
    }
  }
}

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

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

데이터 메시지

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

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

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

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

데이터 메시지 암호화

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

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

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

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

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

다음은 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 객체에 제공되는 모든 필드를 설정할 수 있습니다. 여기에는 다음이 포함됩니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Android와 웹 플랫폼의 경우 TTL(수명)을 길게 설정하지만 APN(Apple 플랫폼) 메시지 우선순위는 낮게 설정합니다.
  • 사용자가 Android와 Apple의 알림을 탭할 경우의 결과를 정의하기 위해 각각 click_actioncategory의 적절한 키를 설정합니다.
{
  "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 Console에 등록된 앱 패키지 이름입니다. FCM 서버는 서로 다른 축소 키를 갖는 축소형 메시지를 기기당 4개씩 동시에 저장할 수 있습니다. 이 한도를 초과하면 FCM에서 축소 키 4개만 보존하며 어떠한 키가 보존되지는 알 수 없습니다.

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

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

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

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

메시지 우선순위 설정

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

  • 보통 우선순위: 보통 우선순위 메시지는 앱이 포그라운드 상태이면 즉시 전송됩니다. 백그라운드 앱의 경우 전송이 지연될 수 있습니다. 새로운 이메일 알림, UI 동기화 유지, 백그라운드 앱 데이터 동기화와 같이 시간이 크게 중요하지 않은 메시지의 경우 보통 전송 우선순위를 선택하세요.

  • 높은 우선순위: FCM이 기기가 잠자기 모드인 경우에도 높은 우선순위 메시지를 즉시 전송하려고 시도합니다. 높은 우선순위 메시지는 사용자에게 표시되는 시간에 민감한 콘텐츠를 위한 것입니다.

다음은 잡지 구독자에게 새 콘텐츠를 다운로드할 수 있다고 알리기 위해 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에서 바로 전송됩니다. 하지만 바로 전송하는 것이 불가능한 경우도 있습니다. 예를 들어 플랫폼이 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이 모든 발신자에게 확장 가능한 서비스를 제공하도록 범위를 지정해야 하는 경우도 있습니다.

축소형 메시지 제한

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

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

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

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

XMPP 서버 제한

FCM XMPP 서버에 연결할 수 있는 속도를 프로젝트당 1분에 400개의 연결로 제한합니다. 메시지 전송에 문제가 생겨서는 안 되지만 시스템의 안정성을 확보하는 것이 중요합니다.

프로젝트마다 FCM에서 동시 연결 2,500개를 허용합니다.

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

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

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

업스트림 메시지 한도

업스트림 대상 서버에 과부하가 걸리지 않도록 업스트림 메시지를 프로젝트당 1,500,000/분으로 제한합니다.

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

주제 메시지 한도

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

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

팬아웃 제한

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

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

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

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에서 사용자 휴대기기의 배터리 소비를 줄이면서 안정적인 연결을 제공할 수 있습니다.

사용자 인증 정보

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

프로젝트 ID Firebase 프로젝트의 고유 식별자로서 FCM v1 HTTP 엔드포인트에 관한 요청에 사용됩니다. 이 값은 Firebase Console 설정 창에서 확인할 수 있습니다.
등록 토큰

각 클라이언트 앱 인스턴스를 식별하는 고유한 토큰 문자열입니다. 단일 기기 및 기기 그룹 메시징에 등록 토큰이 필요합니다. 등록 토큰은 비밀로 유지되어야 한다는 점에 유의하세요.

발신자 ID Firebase 프로젝트를 만들 때 생성되는 고유한 숫자 값으로서 Firebase Console 설정 창의 클라우드 메시징 탭에서 확인할 수 있습니다. 발신자 ID는 클라이언트 앱에 메시지를 보낼 수 있는 각 발신자를 식별하는 데 사용됩니다.
액세스 토큰 HTTP v1 API에 대한 요청을 승인하는 단기 OAuth 2.0 토큰입니다. 이 토큰이 Firebase 프로젝트에 속한 서비스 계정에 연결됩니다. 액세스 토큰을 만들고 순환하려면 보내기 요청 승인에 설명된 단계를 따르세요.
서버 키(기존 프로토콜용)

앱 서버가 Firebase 클라우드 메시징 이전 프로토콜을 통한 메시지 전송과 같은 Google 서비스에 액세스할 수 있도록 인증하는 서버 키입니다. Firebase 프로젝트를 만들 때 서버 키를 부여받습니다. Firebase Console 설정 창의 클라우드 메시징 탭에서 이 서버 키를 확인할 수 있습니다.

중요: 클라이언트 코드에 서버 키를 포함하지 마세요. 또한 앱 서버를 인증할 때 서버 키만 사용해야 합니다. Android, Apple 플랫폼, 브라우저 키는 FCM에서 거부합니다.