2025년 11월 07일
7분

[Android] 푸시 알림(FCM) 완벽 도입 가이드: Firebase & V1 API 필수 세팅 총정리

서비스 운영
KKingmo

Changmo Oh

@KKingmo

전체 글 보기

안드로이드 푸시 알림을 구현하려면 Google의 Firebase Cloud Messaging(FCM)을 반드시 거쳐야 한다. 코드를 짜기 전, 앱과 서버가 Firebase와 통신할 수 있도록 길을 뚫어주는 작업이 필요하다. 특히 최신 HTTP v1 API를 기준으로 작성되었으니 구식 자료(Legacy API)에 낚이지 않도록 주의하자.

전체 구조도

구축할 흐름은 다음과 같다.

  1. Firebase Project: 푸시 알림을 중계하는 본부다.
  2. google-services.json: 안드로이드 앱이 "나 이 프로젝트 소속이야"라고 인증하는 파일이다.
  3. Service Account (비공개 키): 백엔드 서버가 "나 관리자인데 알림 좀 보내줘"라고 요청할 때 쓰는 보안 키다.

Step 1. Firebase 프로젝트 생성

모든 것의 시작이다. 이미 사용하는 Firebase 프로젝트가 있다면 건너뛰어도 좋다.

  1. Firebase Console 접속.
  2. [프로젝트 추가] 클릭.
  3. 프로젝트 이름 입력 (예: myapp-push-project).
  4. Google Analytics 설정은 선택 사항이다 (푸시 수신 통계를 보려면 켜는 게 좋다).
  5. 프로젝트 생성 완료.

Step 2. 안드로이드 앱 등록 (프론트엔드용)

안드로이드 앱을 프로젝트에 연결하고 인증 문서를 발급받는 과정이다.

  1. Firebase Console 메인 화면 중앙의 안드로이드 아이콘(로보트 모양) 클릭.
  2. Android 패키지 이름: 앱의 build.gradle에 있는 applicationId와 똑같이 입력해야 한다 (예: com.example.myapp). 오타 나면 절대 동작 안 하니 주의.
  3. 앱 닉네임: 식별용이니 자유롭게 입력.
  4. 디버그 서명 인증서 SHA-1: 로그인 기능(Google Sign-In)이나 Dynamic Links를 안 쓴다면 단순 푸시용으로는 생략 가능하다. (나중에 필요하면 추가 가능)
  5. [앱 등록] 클릭.
  6. [google-services.json 다운로드] 버튼 클릭.
    • ★중요: 이 파일을 안드로이드 개발자에게 전달한다. (앱 프로젝트의 app/ 폴더 안에 넣어야 한다.)
  7. 이후 단계(SDK 추가 등)는 코드 작업이므로 콘솔에서는 [다음], [콘솔로 이동]을 눌러 넘긴다.

Step 3. 서비스 계정 키 생성 (백엔드용 - 핵심)

가장 중요한 단계다. 과거의 'Server Key' 방식은 더 이상 사용되지 않는다(Deprecated). 백엔드 서버가 FCM 최신 API(HTTP v1)를 쓰기 위해서는 GCP 서비스 계정의 비공개 키가 필요하다.

  1. Firebase Console 좌측 상단 [설정(톱니바퀴)] > [프로젝트 설정] 이동.
  2. [서비스 계정(Service Accounts)] 탭 클릭.
  3. 하단에 'Firebase Admin SDK' 관련 내용이 나온다. 언어는 'Java'나 'Node.js' 아무거나 둬도 상관없다 (우린 키만 필요하다).
  4. [새 비공개 키 생성(Generate new private key)] 버튼 클릭.
  5. 경고창이 뜨면 [키 생성] 클릭.
  6. .json 파일이 다운로드된다.
    • ★중요: 이 파일을 백엔드 개발자에게 전달한다.
    • 이 파일 안에는 project_id, private_key, client_email 등이 들어있다. 서버는 이 파일로 액세스 토큰(OAuth 2.0)을 발급받아 푸시 요청을 보낸다.

Step 4. FCM API 활성화 확인 (자동이지만 확인 필수)

보통 프로젝트 생성 시 자동 활성화되지만, 혹시 모르니 확인한다.

  1. GCP Console 접속 (Firebase와 같은 계정).
  2. 상단 프로젝트 선택기에서 방금 만든 Firebase 프로젝트 선택.
  3. 좌측 메뉴 [API 및 서비스] > [라이브러리] 이동.
  4. Firebase Cloud Messaging API 검색.
  5. [사용(Enable)] 상태인지 확인한다. (안 되어 있다면 클릭해서 활성화).

Step 5. (선택) 테스트 메시지 전송

백엔드 개발이 완료되기 전, 앱 세팅이 잘 됐는지 확인해 볼 수 있다.

  1. Firebase Console 좌측 메뉴 [참여(Engage)] > [Messaging] 이동.
  2. [첫 번째 캠페인 만들기] > [Firebase 알림 메시지] 선택.
  3. 제목과 텍스트 아무거나 입력.
  4. 타겟: 방금 등록한 안드로이드 앱 선택.
  5. [검토] > [게시] 클릭.
  6. 앱이 설치된 폰에서 알림이 오는지 확인한다. (앱이 백그라운드 상태여야 잘 온다.)

세팅 체크리스트

  • Front: google-services.json 파일을 다운로드하여 안드로이드 개발자에게 주었는가?
  • Front: 패키지 이름(com.example...)이 실제 앱 코드와 일치하는가?
  • Back: 서비스 계정 키(...json) 파일을 백엔드 개발자에게 주었는가?
  • Back: 백엔드 개발자에게 우리 프로젝트의 Project ID를 알려주었는가? (V1 API 호출 URL에 필요함: https://fcm.googleapis.com/v1/projects/{ProjectID}/messages:send)

마치며

요약하자면:

  1. 프론트엔드는 google-services.json을 심고 SDK를 초기화한다.
  2. 백엔드는 서비스 계정 json을 이용해 구글 서버 인증 토큰을 받고, HTTP v1 API로 요청을 쏜다.