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

이 문서에서는 앱 서버, 클라이언트 앱, Firebase Cloud Messaging(FCM) 간에 메시지를 전달하는 데 사용되는 XMPP 구문의 참조를 제공합니다. 앱 서버는 다음 엔드포인트에 연결해야 합니다.

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

사용 가능한 매개변수와 옵션은 다음과 같은 카테고리로 분류됩니다.

다운스트림 메시지 구문

이 섹션에서는 다운스트림 메시지를 보내기 위한 구문을 제공합니다.

다운스트림 XMPP 메시지(JSON)

다음 표에서는 XMPP JSON 메시지의 대상, 옵션 및 페이로드를 보여줍니다.

표 1 다운스트림 XMPP 메시지(JSON)의 대상, 옵션, 페이로드

매개변수 사용 설명
대상
to 선택사항, 문자열

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

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

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

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

지원되는 연산자: &&, ||. 주제 메시지당 최대 2개의 연산자가 지원됩니다.
옵션
message_id 필수, 문자열

이 매개변수는 XMPP 연결에서 메시지를 고유하게 식별합니다.
collapse_key 선택사항, 문자열

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

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

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

priority 선택사항, 문자열

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

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

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

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

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

time_to_live 선택사항, 숫자

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

dry_run 선택사항, 부울

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

기본값은 false입니다.
페이로드
data 선택사항, 객체

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

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

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

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

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

문자열 유형의 값을 사용하는 것이 좋습니다. 객체 또는 문자열이 아닌 기타 데이터 유형(예: 정수 또는 불리언)으로 된 값은 문자열로 변환해야 합니다.
notification 선택사항, 객체 이 매개변수는 사용자에게 표시되는 사전 정의된 알림 페이로드의 키-값 쌍을 지정합니다. 자세한 내용은 알림 페이로드 지원을 참조하세요. 알림 메시지 및 데이터 메시지 옵션의 자세한 내용은 메시지 유형을 참조하세요. Apple 기기로 보내는 메시지에 알림 페이로드가 제공되었거나 content_available 옵션이 true로 설정된 경우 메시지는 APNs를 통해 전송되고, 그렇지 않은 경우에는 FCM을 통해 전송됩니다.

알림 페이로드 지원

다음 표에서는 Apple 플랫폼 및 Android용 알림 메시지를 작성하는 데 사용할 수 있는 사전 정의된 키를 보여줍니다.

표 2a. Apple — 알림 메시지 키

매개변수 사용 설명
title 선택사항, 문자열

알림의 제목입니다.

이 필드는 휴대전화(iPhone)와 태블릿(iPad)에는 표시되지 않습니다.
body 선택사항, 문자열

알림의 본문입니다.
sound 선택사항, 문자열

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

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

badge 선택사항, 문자열

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

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

0으로 설정하면 배지가 삭제됩니다.
click_action 선택사항, 문자열

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

APN 페이로드의 category에 해당합니다.
subtitle 선택사항, 문자열

알림의 부제목입니다.
body_loc_key 선택사항, 문자열

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

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

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

body_loc_args 선택사항, 문자열인 JSON 배열

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

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

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

title_loc_key 선택사항, 문자열

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

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

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

title_loc_args 선택사항, 문자열인 JSON 배열

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

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

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

표 2b. Android — 알림 메시지 키

매개변수 사용 설명
title 선택사항, 문자열

알림의 제목입니다.
body 선택사항, 문자열

알림의 본문입니다.
android_channel_id 선택사항, 문자열

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

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

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

icon 선택사항, 문자열

알림 아이콘입니다.

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

sound 선택사항, 문자열

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

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

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

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

지정하면 태그가 동일한 알림이 이미 표시되고 있는 경우 새 알림이 알림 창의 기존 알림을 대체합니다.
color 선택사항, 문자열

#rrggbb 형식으로 표현한 알림 아이콘 색상입니다.
click_action 선택사항, 문자열

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

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

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

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

body_loc_args 선택사항, 문자열인 JSON 배열

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

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

title_loc_key 선택사항, 문자열

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

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

title_loc_args 선택사항, 문자열인 JSON 배열

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

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

표 2c. 웹(자바스크립트) — 알림 메시지 키

매개변수 사용 설명
title 선택사항, 문자열

알림의 제목입니다.
body 선택사항, 문자열

알림의 본문입니다.
icon 선택사항, 문자열

알림 아이콘에 사용할 URL입니다.
click_action 선택사항, 문자열

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

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

다운스트림 XMPP 메시지 응답 해석

다음 표에는 다운스트림 XMPP 메시지 응답에 표시되는 필드가 나와 있습니다.

표 3 다운스트림 메시지 XMPP 응답 본문

매개변수 사용 설명
from 필수, 문자열

이 매개변수는 응답을 보낸 발신자를 지정합니다.

값은 클라이언트 앱의 등록 토큰입니다.
message_id 필수, 문자열 이 매개변수는 XMPP 연결에서 메시지를 고유하게 식별합니다. 값은 관련 메시지를 고유하게 식별하는 문자열입니다.
message_type 필수, 문자열

이 매개변수는 FCM에서 앱 서버로 보내는 ack 또는 nack 메시지를 지정합니다.

값이 nack으로 설정되어 있으면 앱 서버가 error 및 error_description을 확인하여 실패 정보를 가져옵니다.
error 선택사항, 문자열 이 매개변수는 다운스트림 메시지와 관련된 오류를 지정합니다. message_type이 nack인 경우에 설정됩니다. 자세한 내용은 표 4를 참조하세요.
error_description 선택사항, 문자열 이 매개변수는 오류에 대해 설명하는 정보를 제공합니다. message_type이 nack인 경우에 설정됩니다.

다운스트림 메시지 오류 응답 코드

다음 표에는 다운스트림 메시지의 오류 응답 코드가 나와 있습니다.

표 4 다운스트림 메시지 오류 응답 코드

오류 XMPP 코드 권장 조치
누락된 등록 토큰 INVALID_JSON 요청에 등록 토큰이 포함되어 있는지 확인하세요. 일반 텍스트 메시지의 registration_id나 JSON의 to 또는 registration_ids 필드를 확인하세요.
잘못된 APN 등록 INVALID_JSON iOS 등록의 경우 클라이언트의 등록 요청에 유효한 APN 토큰과 애플리케이션 ID가 포함되어 있는지 확인하세요.
잘못된 등록 토큰 BAD_REGISTRATION 서버에 전달한 등록 토큰의 형식을 확인하세요. FCM에 등록할 때 클라이언트 앱이 수신하는 등록 토큰과 일치하는지 확인합니다. 일부분 자르거나 다른 문자를 추가해서는 안 됩니다.
등록되지 않은 기기 DEVICE_UNREGISTERED 다음을 비롯한 몇몇 상황에서는 기존 등록 코드가 더 이상 유효하지 않게 될 수 있습니다.
  • 클라이언트 앱이 FCM에서 등록 해제되었습니다.
  • 클라이언트 앱이 자동으로 등록 해제되었습니다. 사용자가 애플리케이션을 제거한 경우에 발생할 수 있습니다. 예를 들어 iOS에서 APN이 APN 토큰이 잘못되었다고 보고한 경우입니다.
  • 등록 토큰이 만료되었습니다. 예를 들어 Google에서 등록 토큰 새로고침을 결정한 경우이거나 APN 토큰이 기기에서 만료된 경우입니다.
  • 클라이언트 앱이 업데이트되었지만 새 버전이 메시지를 수신할 수 있도록 구성되지 않았습니다.
위와 같은 경우에는 앱 서버에서 등록 토큰을 삭제하고 더 이상 메시지 전송에 이 등록 토큰을 사용하지 마세요.
일치하지 않는 발신자 SENDER_ID_MISMATCH 등록 토큰은 특정 발신자 그룹에 연결됩니다. 클라이언트 앱을 FCM에 등록할 때 메시지를 보낼 수 있는 발신자를 지정해야 합니다. 클라이언트 앱에 메일을 보낼 때는 발신자 ID 중 하나를 사용해야 합니다. 다른 발신자로 전환하면 기존 등록 토큰이 작동하지 않습니다.
JSON이 잘못되었습니다. INVALID_JSON JSON 메시지의 형식이 올바르게 지정되었으며 올바른 필드가 포함되어 있는지 확인하세요. 예를 들어 올바른 데이터 유형이 전달되는지 확인해야 합니다.
너무 큰 메시지 INVALID_JSON 메시지에 포함된 페이로드 데이터의 총 크기가 FCM 한도를 초과하지 않았는지 확인하세요. 대부분의 메시지는 4,096바이트이며 주제로 보내는 메시지의 경우는 2,048바이트입니다. 여기에는 키와 값이 모두 포함됩니다.
잘못된 데이터 키 INVALID_JSON 페이로드 데이터에 FCM에서 내부적으로 사용하는 키(예: from, gcm 또는 프리픽스가 google인 모든 값)가 포함되지 않았는지 확인하세요. 또한 페이로드 값이 FCM 값에 의해 재정의되는 경우에는 FCM에서 사용하는 collapse_key와 같은 일부 단어가 페이로드에도 허용된다는 점에 유의하세요.
잘못된 수명 INVALID_JSON time_to_live에서 사용한 값이 0초에서 2,419,200초(4주) 사이의 기간을 나타내는 정수인지 확인하세요.
잘못된 ACK 메시지 BAD_ACK 다시 시도하기 전에 ack 메시지의 형식이 올바르게 지정되었는지 확인하세요. 자세한 내용은 표 6을 참조하세요.
시간 초과 SERVICE_UNAVAILABLE

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

  • 재시도 방식에 지수 백오프를 적용합니다. (예를 들어 첫 번째 재시도 전에 1초 동안 기다렸다면 다음에는 2초, 그 다음에는 4초 동안 기다리는 식으로 대기 시간을 점차 늘립니다.) 여러 메시지를 보내는 경우에는 동시에 모든 메시지에 대한 새로운 요청을 만들지 않도록 메시지마다 개별적으로 임의의 지연 시간을 추가하세요.
  • 초기 재시도 지연 시간은 1초로 설정되어야 합니다.

참고: 문제를 유발하는 발신자는 차단될 수 있습니다.
내부 서버 오류 INTERNAL_SERVER_
ERROR		 요청을 처리하려고 시도하는 중에 서버에 오류가 발생했습니다. '제한 시간'에 나와 있는 요구사항에 따라 동일한 요청을 다시 시도할 수 있습니다.
기기 메시지 비율 초과 DEVICE_MESSAGE_RATE
_EXCEEDED		 특정 기기로 전달되는 메시지 비율이 너무 높습니다. 이 기기로 보내는 메시지 수를 줄이세요. 이 기기로 바로 다시 보내도록 시도해서는 안 됩니다.
주제 메시지 비율 초과 TOPICS_MESSAGE_RATE
_EXCEEDED		 특정 주제의 구독자에게 전달되는 메시지 비율이 너무 높습니다. 이 주제로 보내는 메시지 수를 줄이세요. 바로 다시 보내도록 시도해서는 안 됩니다.
연결 드레이닝 CONNECTION_DRAINING 연결 드레이닝 중이므로 메시지를 처리하지 못했습니다. 이러한 문제는 FCM이 주기적으로 연결을 종료하여 부하 분산을 수행해야 하기 때문에 발생합니다. 다른 XMPP 연결을 통해 메시지 전송을 다시 시도하세요.
잘못된 APN 인증 정보 INVALID_APNS_CREDENTIAL 필수 APNs 인증 키가 업로드되지 않았거나 만료되어 iOS 기기를 타겟팅한 메시지를 보내지 못했습니다. 개발 및 프로덕션 인증 정보의 유효성을 확인하세요.
인증 실패 AUTHENTICATION_FAILED 외부 푸시 서비스로 인증할 수 없습니다. 올바른 웹 푸시 인증서를 사용하고 있는지 확인하세요.

업스트림 메시지 구문

업스트림 메시지는 클라이언트 앱에서 앱 서버로 보내는 메시지입니다. 현재 XMPP에서만 업스트림 메시징을 지원합니다. 클라이언트 앱에서 메시지를 보내는 방법의 자세한 내용은 플랫폼별 문서를 참조하세요.

업스트림 XMPP 메시지 해석

다음 표에서는 클라이언트 앱의 업스트림 메시지 요청에 대한 응답으로 FCM에서 생성하는 XMPP 스탠자의 필드를 설명합니다.

표 5 업스트림 XMPP 메시지

매개변수 사용 설명
from 필수, 문자열

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

값은 클라이언트 앱의 등록 토큰입니다.
category 필수, 문자열 이 매개변수는 메시지를 보낸 클라이언트 앱의 애플리케이션 패키지 이름을 지정합니다.
message_id 필수, 문자열 이 매개변수는 메시지의 고유 ID를 지정합니다.
data 선택사항, 문자열 이 매개변수는 메시지 페이로드의 키-값 쌍을 지정합니다.

ACK 메시지 전송

다음 표에서는 앱 서버가 수신한 업스트림 메시지에 대한 응답으로 앱 서버에서 FCM으로 보낼 것으로 예상되는 ACK 응답을 설명합니다.

표 6 업스트림 XMPP 메시지 응답

매개변수 사용 설명
to 필수, 문자열

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

값은 업스트림 메시지를 보낸 클라이언트 앱의 등록 토큰이어야 합니다.
message_id 필수, 문자열 이 매개변수는 응답 대상인 메시지를 지정합니다. 값은 해당하는 업스트림 메시지의 message_id 값이어야 합니다.
message_type 필수, 문자열 이 매개변수는 앱 서버에서 CCS로 전달되는 ack 메시지를 지정합니다. 업스트림 메시지의 경우 항상 ack로 설정되어야 합니다.

FCM 서버 메시지(XMPP)

FCM에서 앱 서버로 보내는 메시지입니다. 다음은 FCM에서 앱 서버로 보내는 메시지의 기본 유형입니다.

  • 관리: CCS에서 생성한 이러한 메시지는 앱 서버의 작업이 필요함을 나타냅니다.

다음 표에서는 CCS에서 앱 서버로 보내는 메시지에 포함된 필드를 설명합니다.

표 7 FCM 관리 메시지(XMPP)

매개변수 사용 설명
일반 필드
message_type 필수, 문자열

이 매개변수는 메시지의 유형을 control로 지정합니다.

control로 설정되어 있으면 관리 메시지의 유형을 나타내기 위해 메시지에 control_type이 포함됩니다.
control_type 선택사항, 문자열

이 매개변수는 FCM에서 보낸 관리 메시지의 유형을 지정합니다.

현재 CONNECTION_DRAINING만 지원됩니다. FCM에서 부하 분산을 수행하기 위해 연결을 종료하기 전에 이 관리 메시지를 보냅니다. 연결이 드레이닝되므로 더 이상 이 연결로 메시지를 보낼 수 없지만 파이프라인에 있는 기존 메시지는 계속해서 처리됩니다.