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

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

// 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개의 서로 다른 이미지를 동시에 저장할 수 있음 메시지 수를 표시합니다. 만약 이 숫자를 초과하는 경우 어떤 축소 키 4개가 FCM인지는 보장되지 않습니다. 유지될 것입니다.

priority 선택사항, 문자열

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

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

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

Apple 플랫폼에서는 이 필드를 사용하여 APN 페이로드의 content-available를 나타냅니다. 알림이나 메시지가 전송될 때 true로 설정되어 있으면 비활성 클라이언트 앱이 활성 상태로 전환되고 메시지가 APN을 통해 무음으로 전송됩니다. FCM를 통해서가 아니라 알림을 받습니다. 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(으)로 설정됨 메시지가 APN을 통해 전송되고, 그렇지 않은 경우에는 다음을 통해 전송됩니다. 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 필수, 문자열

이 매개변수는acknack 앱 서버에 대한 FCM

값이 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 페이로드 데이터에 키 (예: from, gcm 또는 임의의 값 접두사 google가 붙으며 FCM에서 내부적으로 사용됩니다. 일부 단어 (예: collapse_key) FCM에서도 사용되지만 페이로드에서 허용되는 경우 페이로드 값이 FCM 값으로 재정의됩니다.
잘못된 수명 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 메시지 해석

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

표 5 업스트림 XMPP 메시지

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

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

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

ACK 메시지 전송

다음 표에서는 앱 서버가 전송할 것으로 예상되는 ACK 응답을 설명합니다. 다음에 대한 응답: FCM 업스트림 메시지를 전송합니다.

표 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에서 이 관리 메시지를 전송합니다. 해야 합니다. 연결이 드레이닝되므로 더 이상 이 연결로 메시지를 보낼 수 없지만 파이프라인에 있는 기존 메시지는 계속해서 처리됩니다.