Firebase 클라우드 메시징 HTTP 프로토콜

이 매개변수는 메시지의 수신자를 지정합니다.

이 값은 기기의 등록 토큰, 기기 그룹의 알림 키 또는 단일 주제(/topics/ 프리픽스 포함)가 될 수 있습니다. 여러 주제로 전송하려면 condition 매개변수를 사용하세요.

이 매개변수는 멀티캐스트 메시지(둘 이상의 등록 토큰으로 전송된 메시지)의 수신자를 지정합니다.

이 값은 멀티캐스트 메시지를 보낼 등록 토큰의 배열이어야 합니다. 배열에 포함될 수 있는 등록 토큰 수는 1~1,000개입니다. 단일 기기로 메시지를 보내려면 to 매개변수를 사용하세요.

멀티캐스트 메시지에는 HTTP JSON 형식만 사용할 수 있습니다.

이 매개변수는 메시지 대상을 결정하는 조건의 논리식을 지정합니다.

지원되는 조건은 형식이 ''yourTopic' in topics'로 지정된 주제입니다. 이 값은 대소문자를 구분하지 않습니다.

지원되는 연산자: &&, ||. 주제 메시지당 최대 2개의 연산자가 지원됩니다.

이 매개변수는 지원 중단되었습니다. 대신 to를 사용하여 메시지 수신자를 지정하세요. 여러 기기로 메시지를 보내는 방법의 자세한 내용은 플랫폼별 문서를 참조하세요.

이 매개변수는 축소 가능한 메시지 그룹(예: collapse_key: "Updates Available" 포함)을 식별하므로, 전송을 재개할 수 있을 때 마지막 메시지만 전송됩니다. 이는 기기가 다시 온라인 또는 활성 상태가 되었을 때 동일한 메시지가 너무 많이 전송되는 것을 방지하기 위함입니다.

메시지가 전송되는 순서는 보장되지 않는다는 점에 유의하세요.

참고: 지정한 기간에 최대 4개의 다른 축소 키가 허용됩니다. 즉, FCM은 클라이언트 앱당 4개의 서로 다른 메시지를 동시에 저장할 수 있습니다. 이 한도를 초과하면 FCM이 어떤 축소 키 4개를 유지할지 확실히 알 수 없습니다.

메시지의 우선순위를 설정합니다. 유효한 값은 'normal' 및 'high'입니다. Apple 플랫폼에서는 APNs 우선순위 5 및 10에 해당합니다.

기본적으로 알림 메시지는 높은 우선순위로, 데이터 메시지는 보통 우선순위로 전송됩니다. 보통 우선순위는 클라이언트 앱의 배터리 사용을 최적화하기 때문에 즉시 전송해야 하는 경우가 아니라면 이 우선순위를 사용하는 것이 좋습니다. 우선순위가 보통인 메시지의 경우 앱이 메시지를 수신할 때 알 수 없는 지연이 발생할 수 있습니다.

높은 우선순위로 메시지를 보내면 즉시 전송되며 앱에 알림이 표시될 수 있습니다.

Apple 플랫폼에서는 이 필드를 사용하여 APNs 페이로드의 content-available을 나타냅니다. 알림이나 메시지가 전송될 때 이 매개변수가 true로 설정되어 있으면 비활성 클라이언트 앱이 활성 상태로 전환되고, 메시지가 FCM이 아니라 APN을 통해 무음 알림으로 전송됩니다. APN의 무음 알림은 확실히 전달된다는 보장이 없으며 사용자가 저전력 모드를 켜거나 앱을 강제 종료하는 등의 요인에 좌우될 수 있습니다. Android에서는 데이터 메시지가 기본적으로 앱을 활성 상태로 전환합니다. Chrome에서는 현재 지원되지 않습니다.

Apple 플랫폼에서는 이 필드를 사용하여 APNs 페이로드의 mutable-content를 나타냅니다. 알림을 전송할 때 이 매개변수가 true로 설정되어 있으면 알림을 표시하기 전에 알림 서비스 앱 확장 프로그램을 사용하여 내용을 수정할 수 있습니다. Android 및 웹에서는 이 매개변수가 무시됩니다.

이 매개변수는 기기가 오프라인 상태인 경우 FCM 스토리지에 메시지를 보관해야 하는 시간(초)을 지정합니다. 지원되는 최대 수명은 4주이며 기본값도 4주입니다. 자세한 내용은 메시지 수명 설정을 참조하세요.

이 매개변수가 true로 설정되어 있으면 개발자가 실제로 메시지를 보내지 않고도 요청을 테스트할 수 있습니다.

기본값은 false입니다.

이 매개변수는 메시지 페이로드의 커스텀 키-값 쌍을 지정합니다.

예를 들면 data:{"score":"3x1"}:입니다.

Apple 플랫폼에서는 메시지가 APN을 통해 전송되는 경우 커스텀 데이터 필드를 나타냅니다. FCM을 통해 전송되는 경우에는 AppDelegate application:didReceiveRemoteNotification:의 키 값 사전으로 표시됩니다.

Android에서는 문자열 값이 3x1인 score라는 추가 인텐트가 생성됩니다.

키는 예약어('google'이나 'gcm'으로 시작하는 모든 단어 또는 'from', 'message_type')여서는 안 됩니다. 이 표에 정의되어 있는 모든 단어(예: collapse_key)도 사용해서는 안 됩니다.

문자열 유형의 값을 사용하는 것이 좋습니다. 객체 또는 문자열이 아닌 기타 데이터 유형(예: 정수 또는 불리언)으로 된 값은 문자열로 변환해야 합니다.

알림의 제목입니다.

이 필드는 휴대전화(iPhone)와 태블릿(iPad)에는 표시되지 않습니다.

알림의 본문입니다.

기기가 알림을 수신하면 재생할 알림음입니다.

클라이언트 앱의 기본 번들 또는 앱 데이터 컨테이너의 Library/Sounds 폴더에 있는 알림음 파일을 지정하는 문자열입니다. 자세한 내용은 iOS 개발자 라이브러리를 참조하세요.

홈 화면 앱 아이콘의 배지 값입니다.

지정하지 않으면 배지가 변경되지 않습니다.

0으로 설정하면 배지가 삭제됩니다.

사용자의 알림 클릭과 관련된 작업입니다.

APN 페이로드의 category에 해당합니다.

알림의 부제목입니다.

앱의 문자열 리소스에서 본문을 사용자의 현재 지역으로 현지화하는 데 사용할 본문 문자열의 키입니다.

APN 페이로드의 loc-key에 해당합니다.

자세한 내용은 Payload Key Reference 및 Localizing the Content of Your Remote Notifications를 확인하세요.

본문을 사용자의 현재 지역으로 현지화하는 데 사용하기 위해 body_loc_key의 형식 지정자 대신 사용할 변수 문자열 값입니다.

APN 페이로드의 loc-args에 해당합니다.

자세한 내용은 Payload Key Reference 및 Localizing the Content of Your Remote Notifications를 확인하세요.

앱의 문자열 리소스에서 제목을 사용자의 현재 지역으로 현지화하는 데 사용할 제목 문자열의 키입니다.

APN 페이로드의 title-loc-key에 해당합니다.

자세한 내용은 Payload Key Reference 및 Localizing the Content of Your Remote Notifications를 확인하세요.

제목을 사용자의 현재 지역으로 현지화하는 데 사용하기 위해 title_loc_key의 형식 지정자 대신 사용할 변수 문자열 값입니다.

APN 페이로드의 title-loc-args에 해당합니다.

자세한 내용은 Payload Key Reference 및 Localizing the Content of Your Remote Notifications를 확인하세요.

알림의 제목입니다.

알림의 본문입니다.

Android O에서 새로 추가된 알림의 채널 ID입니다.

이 채널 ID가 있는 알림을 받으려면 앱에서 이 채널 ID로 채널을 만들어야 합니다.

요청에서 이 채널 ID를 보내지 않거나 제공된 채널 ID가 앱에서 아직 만들어지지 않은 경우 FCM은 앱 매니페스트에 지정된 채널 ID를 사용합니다.

알림 아이콘입니다.

드로어블 리소스 myicon에 대한 알림 아이콘을 myicon으로 설정합니다. 요청에서 이 키를 전송하지 않으면 FCM은 앱 매니페스트에 지정된 런처 아이콘을 표시합니다.

기기가 알림을 수신하면 재생할 알림음입니다.

"default" 또는 앱에 번들로 포함된 사운드 리소스의 파일 이름을 지원합니다. 사운드 파일은 /res/raw/에 있어야 합니다.

알림 창에서 기존 알림을 대체하는 데 사용되는 식별자입니다.

지정하지 않으면 각 요청이 새 알림을 만듭니다.

지정하면 태그가 동일한 알림이 이미 표시되고 있는 경우 새 알림이 알림 창의 기존 알림을 대체합니다.

#rrggbb 형식으로 표현한 알림 아이콘 색상입니다.

사용자의 알림 클릭과 관련된 작업입니다.

지정하면 사용자가 알림을 클릭할 때 일치하는 인텐트 필터가 있는 액티비티가 실행됩니다.

앱의 문자열 리소스에서 본문을 사용자의 현재 지역으로 현지화하는 데 사용할 본문 문자열의 키입니다.

자세한 내용은 문자열 리소스를 참조하세요.

본문을 사용자의 현재 지역으로 현지화하는 데 사용하기 위해 body_loc_key의 형식 지정자 대신 사용할 변수 문자열 값입니다.

자세한 내용은 형식 및 스타일 지정을 참조하세요.

앱의 문자열 리소스에서 제목을 사용자의 현재 지역으로 현지화하는 데 사용할 제목 문자열의 키입니다.

자세한 내용은 문자열 리소스를 참조하세요.

제목을 사용자의 현재 지역으로 현지화하는 데 사용하기 위해 title_loc_key의 형식 지정자 대신 사용할 변수 문자열 값입니다.

자세한 내용은 형식 및 스타일 지정을 참조하세요.

알림의 제목입니다.

알림의 본문입니다.

알림 아이콘에 사용할 URL입니다.

사용자의 알림 클릭과 관련된 작업입니다.

모든 URL 값은 보안 HTTPS여야 합니다.

이 매개변수는 메시지를 수신하는 클라이언트 앱의 등록 토큰을 지정합니다.

2개 이상의 등록 토큰으로 보내는 멀티캐스트 메시징에는 HTTP JSON 형식만 사용할 수 있습니다.

이 매개변수는 메시지 페이로드의 키-값 쌍을 지정합니다. 키-값 매개변수의 수에는 제한이 없지만 총 메시지 크기가 4,096바이트로 제한됩니다.

예를 들어 Android에서 "data.score"."3x1"은 문자열 값이 3x1인 score라는 추가 인텐트를 생성합니다.

키는 예약어('google'이나 'gcm'으로 시작하는 모든 단어 또는 'from', 'message_type')여서는 안 됩니다. 이 표에 정의되어 있는 모든 단어(예: collapse_key)도 사용해서는 안 됩니다.

• message_id: 성공적으로 처리된 각 메시지의 고유 ID를 지정하는 문자열입니다.
• error: 수신자의 메시지를 처리할 때 발생한 오류를 지정하는 문자열입니다. 가능한 값은 표 9에서 확인할 수 있습니다.

• 클라이언트 앱이 FCM에서 등록 해제되었습니다.
• 클라이언트 앱이 자동으로 등록 해제되었습니다. 사용자가 애플리케이션을 제거한 경우에 발생할 수 있습니다. 예를 들어 iOS에서 APNs 피드백 서비스가 APNs 토큰이 잘못되었다고 보고한 경우입니다.
• 등록 토큰이 만료되었습니다. 예를 들어 Google에서 등록 토큰 새로고침을 결정한 경우이거나 APNs 토큰이 iOS 기기에서 만료된 경우입니다.
• 클라이언트 앱이 업데이트되었지만 새 버전이 메시지를 수신할 수 있도록 구성되지 않았습니다.

• 승인 헤더가 누락되었거나 HTTP 요청에 잘못된 구문이 있습니다.
• 지정한 서버 키가 속한 Firebase 프로젝트가 잘못되었습니다.
• 이전 서버 키만 해당 - 서버에서 시작된 요청이 서버 키 IP의 허용 목록에 없습니다.

서버에서 시간 내에 요청을 처리하지 못했습니다. 동일한 요청을 다시 시도하되 다음을 수행해야 합니다.

• FCM 연결 서버의 응답에 포함된 경우 Retry-After 헤더를 반영합니다.
• 재시도 방식에서 지수 백오프를 구현합니다. (예를 들어 첫 번째 재시도 전에 1초 동안 기다렸다면 다음에는 2초, 그 다음에는 4초 동안 기다리는 식으로 대기 시간을 점차 늘립니다.) 여러 메시지를 보내는 경우에는 동시에 모든 메시지에 대한 새로운 요청을 만들지 않도록 메시지마다 개별적으로 임의의 지연 시간을 추가하세요.

문제를 유발하는 발신자는 차단될 수 있습니다.

특정 기기로 전달되는 메시지 비율이 너무 높습니다. Apple 앱의 메시지 전송 속도가 APNs 한도를 초과하면 이 오류 메시지가 표시될 수 있습니다.

이 기기로 보내는 메시지 수를 줄이고 전송을 재시도할 때 지수 백오프를 사용하세요.