FCM HTTP API 완벽 정복: 레거시부터 최신 v1 API까지 ~ Dev.

Firebase Cloud Messaging(FCM)은 애플리케이션 서버와 클라이언트 앱 간의 안정적인 메시지 전송을 위한 강력한 크로스플랫폼 메시징 솔루션입니다. 개발자는 서버에서 직접 HTTP 요청을 보내 사용자에게 푸시 알림을 발송할 수 있는데, 이 과정에서 종종 오래된 문서나 부정확한 정보로 인해 혼란을 겪곤 합니다. 특히, 공식 영문 문서와 다른 언어의 문서 간에 업데이트 시차가 발생하면서 예기치 않은 오류를 마주하는 경우가 많습니다.

이 글에서는 과거에 사용되던 FCM 레거시(Legacy) HTTP API부터 현재 Google이 공식적으로 권장하는 최신 HTTP v1 API, 그리고 가장 편리한 방법인 Firebase Admin SDK 사용법까지 심도 있게 비교하고 분석하여, FCM 메시지 발송 시 겪을 수 있는 모든 궁금증을 해결해 드립니다.

과거의 유산, FCM 레거시(Legacy) HTTP API

FCM의 전신인 GCM(Google Cloud Messaging) 시절부터 사용되어 온 API로, 많은 구형 튜토리얼이나 블로그 글에서 여전히 이 방식을 소개하고 있습니다. 현재는 레거시(Legacy)로 분류되며, 신규 프로젝트에서는 사용을 권장하지 않습니다. 하지만 기존 시스템을 유지보수하거나 오래된 자료를 참고할 때 이 API를 마주칠 수 있으므로 구조를 이해하는 것은 중요합니다.

레거시 API는 다음과 같은 특징을 가집니다.

엔드포인트: https://fcm.googleapis.com/fcm/send
인증 방식: Firebase 프로젝트 설정에서 발급받는 정적인 서버 키(Server Key)를 사용합니다. 이 키는 유효 기간이 없어 한번 유출되면 보안에 매우 취약할 수 있습니다.
요청 형식: JSON 페이로드의 최상위 레벨에 수신자, 알림 내용 등을 직접 정의합니다.

레거시 API 요청 예시

레거시 API를 사용하여 특정 기기에 알림을 보내는 기본적인 요청 형식은 다음과 같습니다.

# HTTP 요청 헤더
POST /fcm/send HTTP/1.1
Host: fcm.googleapis.com
Authorization: key=AIzaSy...YOUR_SERVER_KEY
Content-Type: application/json

# HTTP 요청 본문 (Body)
{
  "to": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "notification": {
    "title": "새로운 메시지 도착",
    "body": "레거시 API를 통해 발송된 메시지입니다.",
    "icon": "stock_ticker_update",
    "click_action": "OPEN_ACTIVITY_1"
  },
  "data": {
    "userId": "user123",
    "messageId": "msg456"
  },
  "priority": "high"
}

주요 필드 설명

Authorization (헤더): key= 접두사 뒤에 Firebase 콘솔의 '클라우드 메시징' 탭에서 확인할 수 있는 서버 키를 붙여 넣습니다.
to: 메시지를 보낼 단일 기기의 등록 토큰(FCM Token)을 지정합니다. 여러 기기에 보내려면 registration_ids 필드를 사용하고 토큰 배열을 전달해야 합니다.
notification: 앱이 백그라운드에 있을 때 시스템 트레이에 표시될 알림의 시각적 요소를 정의합니다. (제목, 내용, 아이콘 등)
data: 클라이언트 앱에서 직접 처리할 수 있는 커스텀 Key-Value 데이터를 포함합니다. 앱이 포그라운드에 있을 때 이 데이터를 받아 특정 로직을 수행할 수 있습니다.
priority: 메시지의 중요도를 나타냅니다. high 또는 normal 값을 가질 수 있으며, high로 설정 시 안드로이드 기기의 도즈 모드(Doze mode)에서도 즉시 전달을 시도합니다.

이 방식은 구현이 비교적 간단하지만, 앞서 언급했듯 보안에 취약하고 플랫폼별 세부 설정(예: iOS의 APNs 페이로드 커스터마이징)에 한계가 있어 현재는 더 발전된 HTTP v1 API로의 전환이 강력히 권장됩니다.

오래된 문서가 초래하는 혼란: 잘못된 요청 형식

원문에서 지적한 문제는 바로 이 레거시 API와 최신 API 사이의 과도기, 혹은 잘못 업데이트된 문서 때문에 발생합니다. 예를 들어, 일부 오래된 한국어 문서에서는 다음과 같은 형식의 페이로드를 안내하기도 했습니다.

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data": {
      "Nick": "Mario",
      "Room": "PortugalVSDenmark"
    }
  }
}

이 구조는 현재의 HTTP v1 API와 매우 유사하지만, 만약 이 페이로드를 레거시 API의 엔드포인트(/fcm/send)와 서버 키 인증 방식으로 전송하면 FCM 서버는 이를 올바르게 해석하지 못합니다. 서버는 최상위 레벨에 to나 registration_ids 필드가 있을 것으로 예상하기 때문입니다. 그 결과, "MissingRegistration" 오류가 발생하거나 원문에서처럼 의미를 알 수 없는 'to'와 같은 응답만 받게 되어 개발자를 혼란에 빠뜨립니다.

이러한 문제는 공식 문서라도 영문 버전을 기준으로 삼고, API 버전을 명확히 확인하는 습관이 중요함을 보여주는 좋은 예시입니다.

현재의 표준, FCM HTTP v1 API

FCM HTTP v1 API는 현재 Google이 공식적으로 권장하는 메시지 발송 방식으로, 보안, 확장성, 기능 면에서 레거시 API보다 월등히 뛰어납니다. 신규 프로젝트를 시작한다면 반드시 v1 API를 사용해야 합니다.

HTTP v1 API의 주요 특징은 다음과 같습니다.

엔드포인트: https://fcm.googleapis.com/v1/projects/YOUR_PROJECT_ID/messages:send
인증 방식: Google API용 OAuth 2.0 액세스 토큰을 사용합니다. 이 토큰은 수명이 짧아(보통 1시간) 보안성이 높으며, 서비스 계정(Service Account)을 통해 발급받습니다.
요청 형식: 모든 메시지 관련 정보를 message 객체로 감싸는 일관된 구조를 가집니다. 이를 통해 플랫폼별(Android, iOS, Web) 세부 설정을 명확하게 구분하여 전송할 수 있습니다.

HTTP v1 API 사용 절차

1. 서비스 계정 키 파일 생성

먼저 서버가 Google API에 자신을 인증할 수 있도록 서비스 계정 키를 발급받아야 합니다.

Firebase 콘솔에서 프로젝트를 열고, '프로젝트 설정' > '서비스 계정' 탭으로 이동합니다.
'새 비공개 키 생성' 버튼을 클릭하여 JSON 형식의 키 파일을 다운로드합니다.
이 파일은 매우 민감한 정보이므로, 절대로 외부에 노출되거나 클라이언트 코드에 포함해서는 안 됩니다. 안전한 서버 환경에 보관하세요.

2. OAuth 2.0 액세스 토큰 생성

다운로드한 서비스 계정 키를 사용하여 프로그래밍 방식으로 액세스 토큰을 요청해야 합니다. Google Auth 라이브러리를 사용하면 이 과정을 쉽게 처리할 수 있습니다. (예: google-auth-library for Node.js, google-auth for Python)

3. HTTP v1 API 요청 보내기

생성된 액세스 토큰을 사용하여 messages:send 엔드포인트에 POST 요청을 보냅니다. 페이로드 구조는 레거시 API와 완전히 다릅니다.

# HTTP 요청 헤더
POST /v1/projects/your-project-id/messages:send HTTP/1.1
Host: fcm.googleapis.com
Authorization: Bearer YOUR_OAUTH2_ACCESS_TOKEN
Content-Type: application/json

# HTTP 요청 본문 (Body)
{
  "message": {
    "token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification": {
      "title": "HTTP v1 알림",
      "body": "더 안전하고 강력한 v1 API로 보낸 메시지입니다!"
    },
    "data": {
      "screen": "detail",
      "itemId": "item_12345"
    },
    "android": {
      "priority": "high",
      "notification": {
        "channel_id": "new_messages_channel"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "badge": 1,
          "sound": "default"
        }
      }
    }
  }
}

v1 API 페이로드의 강력한 기능

message: 모든 메시지 구성 요소를 담는 최상위 객체입니다.
token, topic, condition: 메시지 대상을 지정합니다. 레거시 API의 to와 달리, 토픽 구독자나 복잡한 조건(예: 'TopicA'를 구독하고 'TopicB'는 구독하지 않는 사용자)을 대상으로 메시지를 보낼 수 있습니다.
android, apns, webpush: 각 플랫폼에 특화된 설정을 할 수 있는 객체입니다. 위 예시에서는 안드로이드의 알림 채널(channel_id)을 지정하고, iOS(APNs)의 앱 아이콘 배지(badge) 숫자를 설정했습니다. 이러한 세부 제어는 레거시 API로는 불가능하거나 매우 복잡했습니다.

가장 현명한 선택: Firebase Admin SDK 사용하기

HTTP v1 API는 강력하지만, OAuth 2.0 토큰을 직접 관리하고 HTTP 요청을 수동으로 구성하는 것은 번거롭고 오류가 발생하기 쉽습니다. 그래서 Google은 서버 환경에서 FCM을 사용할 때 Firebase Admin SDK를 사용할 것을 강력히 권장합니다.

Admin SDK는 Node.js, Python, Java, Go, .NET 등 다양한 언어를 지원하며, 다음과 같은 압도적인 장점을 제공합니다.

자동 인증 관리: 서비스 계정 키 파일만 제공하면 SDK가 알아서 OAuth 2.0 액세스 토큰을 발급하고, 만료 시 자동으로 갱신합니다. 개발자는 인증 과정에 전혀 신경 쓸 필요가 없습니다.
직관적인 API: 복잡한 JSON 구조를 직접 만들 필요 없이, 잘 정의된 메서드와 객체를 사용하여 메시지를 구성하고 전송할 수 있습니다.
타입 안정성 및 자동 완성: TypeScript나 Java와 같은 정적 타입 언어에서는 타입 안정성을 제공하여 개발 단계에서 오류를 줄여줍니다.
통합 관리: FCM뿐만 아니라 Firestore, Realtime Database, Authentication 등 다른 Firebase 서비스를 동일한 SDK 인스턴스에서 함께 관리할 수 있습니다.

Firebase Admin SDK (Node.js) 사용 예시

Admin SDK를 사용하면 위의 복잡했던 HTTP 요청이 얼마나 간결해지는지 확인해 보세요.

// 1. SDK 초기화
const admin = require("firebase-admin");
const serviceAccount = require("./path/to/your-service-account-key.json");

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount)
});

// 2. 메시지 정의
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

const message = {
  notification: {
    title: 'Admin SDK 알림',
    body: 'SDK를 사용하니 정말 편리하네요!'
  },
  data: {
    score: '850',
    time: '2:45'
  },
  token: registrationToken
};

// 3. 메시지 발송
admin.messaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

보시다시피, 복잡한 HTTP 헤더 설정이나 인증 토큰 관리가 전혀 필요 없습니다. 단지 SDK를 초기화하고, 메시지 객체를 정의한 뒤 send() 메서드를 호출하기만 하면 됩니다. 내부적으로는 Admin SDK가 안전하게 HTTP v1 API를 호출해 줍니다.

한눈에 보는 API 비교 및 결론

지금까지 살펴본 세 가지 방법의 특징을 표로 정리하면 다음과 같습니다.

구분	레거시 HTTP API	HTTP v1 API (직접 호출)	Firebase Admin SDK
엔드포인트	`/fcm/send`	`/v1/projects/.../messages:send`	SDK가 내부적으로 처리
인증 방식	정적 서버 키 (보안 취약)	단기 OAuth 2.0 토큰 (보안 우수)	OAuth 2.0 자동 관리 (가장 편리)
페이로드 구조	플랫 구조 (`to`, `notification`)	중첩 구조 (`message: { ... }`)	언어별 객체/메서드
플랫폼별 설정	제한적	매우 유연 (`android`, `apns` 등)	메서드를 통해 유연하게 지원
권장 사항	사용 중단 (Deprecated)	서버 언어용 SDK가 없을 경우 사용	강력 권장 (Best Practice)

최종 결론

Firebase Cloud Messaging을 서버에서 연동할 때, 우리는 선택의 기로에 놓입니다. 결론은 명확합니다.

새로운 프로젝트라면 무조건 Firebase Admin SDK를 사용하세요. 개발 생산성, 안정성, 보안 모든 면에서 가장 뛰어난 선택입니다.
Admin SDK가 지원되지 않는 특수한 환경에서만 HTTP v1 API를 직접 호출하는 것을 고려하세요. 이 경우, OAuth 2.0 토큰 관리 로직을 안전하게 구현해야 합니다.
레거시 HTTP API는 기존 시스템 유지보수 목적이 아니라면 더 이상 사용하지 말아야 합니다.
개발 중 문제가 발생하면, 가장 먼저 공식 영문 문서를 확인하여 최신 API 사양과 변경점을 파악하는 것이 중요합니다.

이 가이드를 통해 FCM HTTP API에 대한 혼란이 해결되고, 더 안정적이고 효율적인 푸시 알림 시스템을 구축하는 데 도움이 되기를 바랍니다.

Tuesday, November 13, 2018

FCM HTTP API 완벽 정복: 레거시부터 최신 v1 API까지

과거의 유산, FCM 레거시(Legacy) HTTP API

레거시 API 요청 예시

주요 필드 설명

오래된 문서가 초래하는 혼란: 잘못된 요청 형식

현재의 표준, FCM HTTP v1 API

HTTP v1 API 사용 절차

1. 서비스 계정 키 파일 생성

2. OAuth 2.0 액세스 토큰 생성

3. HTTP v1 API 요청 보내기

v1 API 페이로드의 강력한 기능

가장 현명한 선택: Firebase Admin SDK 사용하기

Firebase Admin SDK (Node.js) 사용 예시

한눈에 보는 API 비교 및 결론

최종 결론

0 개의 댓글:

Post a Comment

Popular Posts

Recent Posts

Comments

Visitor

Followers