앱 서버 보내기 요청 작성

FCM 앱 서버 프로토콜을 사용하여 메시지 요청을 작성하고 다음과 같은 타겟 유형으로 전송할 수 있습니다.

  • 주제 이름
  • 조건
  • 기기 등록 토큰
  • 기기 그룹 이름(기존 프로토콜만 해당)

사전 정의된 필드로 구성된 알림 페이로드 또는 사용자가 직접 정의한 필드로 구성된 데이터 페이로드와 함께 메시지를 보내거나 두 가지 유형의 페이로드를 모두 포함하는 메시지를 보낼 수 있습니다. 자세한 내용은 메시지 유형을 참조하세요. 이 페이지의 예에서는 v1 HTTP 프로토콜로 알림 메시지를 보내는 방법을 보여줍니다. 기존 HTTP 및 XMPP 프로토콜을 통해 메시지를 보내는 방법도 알아보세요.

HTTP를 통해 메시지를 보내려면 FCM v1 엔드포인트로 HTTP POST 요청을 보내고 send 메소드를 지정합니다. 엔드포인트 URL은 Firebase 콘솔의 일반 프로젝트 설정 탭에서 확인할 수 있는 앱의 Firebase 프로젝트 ID를 포함해야 합니다. 예를 들면 다음과 같습니다.

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

요청 헤더에는 다음이 포함되어야 합니다.

  • Content-type: application/json
  • Authorization: Bearer <valid Oauth 2.0 token for the service account of the Firebase project>

OAuth 2.0 액세스 토큰에 대한 자세한 내용은 보내기 요청 승인을 참조하세요.

요청 본문에는 메시지의 옵션과 내용에 대한 JSON 키-값 쌍이 들어 있습니다. FCM 메시지 정보에서 메시지 본문에 사용 가능한 옵션의 개요를 참조하거나 API 참조에서 자세한 내용을 확인하세요.

특정 기기에 메시지 전송

요청 본문에서 message 객체의 token 키를 타겟팅할 특정 앱 인스턴스의 등록 토큰으로 설정합니다. 등록 토큰에 대한 자세한 내용은 플랫폼별 클라이언트 설정 정보를 참조하세요.

v1 API에 대한 모든 HTTP 요청은 액세스 토큰으로 승인되어야 합니다. 서비스 계정 사용자 인증 정보에서 액세스 토큰을 가져오는 방법을 알아보려면 보내기 요청 승인을 참조하세요.

HTTP POST 요청

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
  "message":{
    "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification" : {
      "body" : "This is an FCM notification message!",
      "title" : "FCM Message",
      }
   }
}

cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
  "notification": {
    "title": "FCM Message",
    "body": "This is an FCM Message",
  },
  "token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

HTTP 응답

{
    "name": "projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}

주제로 메시지 전송

Firebase 클라우드 메시징 주제로 메시지를 보내는 것은 개별 기기나 사용자 그룹으로 메시지를 보내는 것과 매우 비슷합니다. 앱 서버는 메시지 본문의 topic 키를 yourTopic 등의 값으로 설정합니다. 개발자는 다음 정규 표현식과 일치하는 모든 주제 이름을 선택할 수 있습니다. "[a-zA-Z0-9-_.~%]+"

여러 주제를 조합하여 보내려면 앱 서버에서 condition 키를 대상 주제를 지정하는 부울 조건으로 설정합니다. 예를 들어 TopicA와 함께 TopicB 또는 TopicC를 구독한 기기로 메시지를 보내는 방법은 다음과 같습니다.

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM이 먼저 괄호의 모든 조건을 확인한 다음 왼쪽에서 오른쪽으로 표현식을 확인합니다. 위 표현식에서는 주제 1개를 구독한 사용자는 메시지를 수신하지 않습니다. 또한 TopicA를 구독하지 않은 사용자도 메시지를 수신하지 않습니다. 다음과 같이 조합되어야 메시지를 수신합니다.

  • TopicA 및 TopicB
  • TopicA 및 TopicC

조건식에 최대 5개의 주제를 포함할 수 있으며 괄호가 지원됩니다. 지원되는 연산자는 &&, ||, !입니다. !의 사용법은 다음과 같습니다.

!('TopicA' in topics)

이 식을 사용하면 어떠한 주제도 구독하지 않는 앱 인스턴스를 포함하여 TopicA를 구독하지 않는 모든 앱 인스턴스가 메시지를 수신합니다.

앱 서버 키에 대한 자세한 내용은 참조 정보를 확인하세요.

주제 HTTP POST 요청

주제 1개로 보내는 방법은 다음과 같습니다.

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

cURL로 보내는 방법은 다음과 같습니다.

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

'dogs' 또는 'cats' 주제를 구독한 기기로 보내는 방법은 다음과 같습니다.

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

cURL로 보내는 방법은 다음과 같습니다.

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

주제 HTTP 응답

{
    "name": "projects/myproject-b5ae1/messages/5735743068807585451"
}

메시지 옵션의 전체 목록은 HTTP v1 API 참조를 확인하세요.

기존 앱 서버 프로토콜을 사용하여 메시지 보내기

기존 프로토콜을 사용하려는 경우 이 섹션의 안내에 따라 메시지 요청을 작성하세요. HTTP를 통해 여러 플랫폼으로 전송하는 경우 v1 프로토콜을 사용하면 메시지 요청이 단순해질 수 있다는 점을 참고하시기 바랍니다.

특정 기기에 메시지 전송

특정 기기로 메시지를 보내려면 to 키를 특정 앱 인스턴스의 등록 토큰으로 설정합니다. 등록 토큰에 대한 자세한 내용은 플랫폼별 클라이언트 설정 정보를 참조하세요.

HTTP POST 요청

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

HTTP 응답

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

XMPP 메시지

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

XMPP 응답

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

XMPP 연결 서버는 몇 가지 다른 응답 옵션을 제공합니다. 서버 응답 형식을 참조하세요.

클라이언트 앱에 다운스트림 메시지를 보낼 때 사용할 수 있는 메시지 옵션의 전체 목록은 HTTP 또는 XMPP 중 선택한 연결 서버 프로토콜에 맞는 참조 정보를 확인하세요.

주제로 메시지 전송

Firebase 클라우드 메시징 주제로 메시지를 보내는 것은 개별 기기나 사용자 그룹으로 메시지를 보내는 것과 매우 비슷합니다. 앱 서버는 to 키를 /topics/yourTopic 등의 값으로 설정합니다. 개발자는 다음 정규 표현식과 일치하는 모든 주제 이름을 선택할 수 있습니다. "/topics/[a-zA-Z0-9-_.~%]+"

여러 주제를 조합하여 보내려면 앱 서버에서 to 키 대신 condition 키를 대상 주제를 지정하는 부울 조건으로 설정해야 합니다. 예를 들어 TopicA와 함께 TopicB 또는 TopicC를 구독한 기기로 메시지를 보내는 방법은 다음과 같습니다.

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM이 먼저 괄호의 모든 조건을 확인한 다음 왼쪽에서 오른쪽으로 표현식을 확인합니다. 위 표현식에서는 주제 1개를 구독한 사용자는 메시지를 수신하지 않습니다. 또한 TopicA를 구독하지 않은 사용자도 메시지를 수신하지 않습니다. 다음과 같이 조합되어야 메시지를 수신합니다.

  • TopicA 및 TopicB
  • TopicA 및 TopicC

조건식에 최대 5개의 주제를 포함할 수 있으며 괄호가 지원됩니다. 지원되는 연산자는 &&, ||, !입니다. !의 사용법은 다음과 같습니다.

!('TopicA' in topics)

이 식을 사용하면 어떠한 주제도 구독하지 않는 앱 인스턴스를 포함하여 TopicA를 구독하지 않는 모든 앱 인스턴스가 메시지를 수신합니다.

앱 서버 키에 대한 자세한 내용은 HTTP 또는 XMPP 중 선택한 연결 서버 프로토콜에 맞는 참조 정보를 확인하세요. 이 페이지의 예에서는 HTTP 및 XMPP에서 주제로 메시지를 보내는 방법을 모두 보여줍니다.

주제 HTTP POST 요청

주제 1개로 보내는 방법은 다음과 같습니다.

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "to": "/topics/foo-bar",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

'dogs' 또는 'cats' 주제를 구독한 기기로 보내는 방법은 다음과 같습니다.

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "condition": "'dogs' in topics || 'cats' in topics",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

주제 HTTP 응답

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

주제 XMPP 메시지

주제 1개로 보내는 방법은 다음과 같습니다.

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "to": "/topics/foo-bar",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

  </gcm>
</message>

'dogs' 또는 'cats' 주제를 구독한 기기로 보내는 방법은 다음과 같습니다.

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "condition": "'dogs' in topics || 'cats' in topics",
  "data": {
    "message": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

  </gcm>
</message>

주제 XMPP 응답

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}

FCM 연결 서버가 주제 전송 요청에 성공 또는 실패 응답을 반환하는 데 최대 30초의 지연이 발생할 수 있습니다. 요청에서 이 지연 시간에 맞게 앱 서버 제한 시간 값을 설정해야 합니다.

메시지 옵션의 전체 목록은 HTTP 또는 XMPP 중 선택한 연결 서버 프로토콜에 맞는 참조 정보를 확인하세요.

기기 그룹에 메시지 전송

기기 그룹에 메시지를 보내는 것은 개별 기기에 메시지를 보내는 것과 매우 비슷합니다. to 매개변수를 기기 그룹의 고유 알림 키로 설정하세요. 페이로드 지원의 자세한 내용은 메시지 유형을 참조하세요. 이 페이지의 예에서는 HTTP 및 XMPP 프로토콜로 기기 그룹에 메시지를 보내는 방법을 확인할 수 있습니다.

기기 그룹 HTTP POST 요청

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

기기 그룹 HTTP 응답

다음은 '성공' 응답의 예입니다. notification_key에 연결된 등록 토큰이 2개 있으며 메시지가 두 토큰에 모두 성공적으로 전송되었습니다.

{
  "success": 2,
  "failure": 0
}

다음은 '부분적인 성공' 응답의 예입니다. notification_key에 연결된 등록 토큰이 3개 있습니다. 메시지가 등록 토큰 1개에만 성공적으로 전송되었습니다. 메시지를 수신하지 못한 등록 토큰이 응답 메시지에 표시됩니다.

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

메시지가 notification_key에 연결된 1개 이상의 등록 토큰에 전송되지 못하면 앱 서버에서 일정한 간격을 두고 재시도해야 합니다.

서버에서 메시지를 보내려는 기기 그룹에 구성원이 없는 경우 다음과 같이 응답의 성공, 실패가 모두 0입니다.

{
  "success": 0,
  "failure": 0
}

기기 그룹 XMPP 메시지

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

기기 그룹 XMPP 응답

그룹에 메시지가 성공적으로 전송된 기기가 있으면 XMPP 연결 서버가 ACK로 응답합니다. 모든 메시지가 그룹의 모든 기기에 전송되지 못하면 XMPP 연결 서버가 NACK로 응답합니다.

다음은 '성공' 응답의 예입니다. notification_key에 연결된 등록 토큰이 3개 있으며 메시지가 모든 토큰에 성공적으로 전송되었습니다.

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

다음은 '부분적인 성공' 응답의 예입니다. notification_key에 연결된 등록 토큰이 3개 있습니다. 메시지가 등록 토큰 1개에만 성공적으로 전송되었습니다. 메시지를 수신하지 못한 등록 토큰이 응답 메시지에 표시됩니다.

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

FCM 연결 서버가 그룹의 모든 기기에 전송하지 못하면 앱 서버가 NACK 응답을 수신합니다.

메시지 옵션의 전체 목록은 HTTP 또는 XMPP 중 선택한 연결 서버 프로토콜에 맞는 참조 정보를 확인하세요.

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.