📄 [문서] FCM 알림 서비스

[Chuseok22]

📝 현재 문제점

• 특정 기능이 부족하거나 개선이 필요한 이유를 작성해주세요.

🛠️ 해결 방안 / 제안 기능

FCM (Firebase Cloud Messaging) 이란?

• Firebase에서 제공하는 무료 푸시 알림 서비스
• 서버에서 클라이언트에 메시지나 알림 전송 가능

구성요소

1. FCM 토큰(Token)
   • 클라이언트에서 발급
   • 서버에서는 해당 토큰을 저장하고 토큰을 이용해 알림 전송
2. Firebase Admin SDK
   • 서버 측에서 FCM에 연결하여 메시지를 전송하기 위한 라이브러리
3. 서비스 계정 키 (Service Account)
   • firebase-service-account.json파일 형태로 발급 → 해당 키로 Firebase Admin SDK 초기화
   • /src/resources/firebase-service-account.json파일 추가
   • .gitignore설정

동작 방식

1. 클라이언트

• Firebase SDK롤 사용하여 앱 구동 시 FCM 토큰 획득
• 서버로 해당 토큰 전송 → 서버에서 저장

2. 서버

• Firebase Admin SDK를 이용해 메시지를 생성, 전송
• 해당 토큰을 가진 기기에 알림 전송

3. FCM 서버

• 서버로 부터 전송된 메시지를 푸시 알림으로 전송

구현

1. FirebaseConfig.java

package com.example.fcm.config;

import com.google.auth.oauth2.GoogleCredentials;
import com.google.firebase.FirebaseApp;
import com.google.firebase.FirebaseOptions;
import org.springframework.context.annotation.Configuration;

import javax.annotation.PostConstruct;
import java.io.IOException;
import java.io.InputStream;

@Configuration
public class FirebaseConfig {

    @PostConstruct
    public void init() {
        try {
            // resources 디렉토리에 있는 서비스 계정 키 파일 로드
            InputStream serviceAccount = getClass()
                    .getResourceAsStream("/firebase-service-account.json");

            FirebaseOptions options = FirebaseOptions.builder()
                    .setCredentials(GoogleCredentials.fromStream(serviceAccount))
                    .build();

            // 이미 FirebaseApp이 초기화되어 있지 않았다면 초기화
            if (FirebaseApp.getApps().isEmpty()) {
                FirebaseApp.initializeApp(options);
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

• @PostConstruct를 이용해 스프링 컨테이너 실행 시 자동으로 Firebase Admin SDK 초기화

2. FcmService.java

package com.example.fcm.service;

import com.google.firebase.messaging.AndroidConfig;
import com.google.firebase.messaging.ApnsConfig;
import com.google.firebase.messaging.Aps;
import com.google.firebase.messaging.Message;
import com.google.firebase.messaging.Notification;
import com.google.firebase.messaging.FirebaseMessaging;
import org.springframework.stereotype.Service;

@Service
public class FcmService {

    /**
     * 단일 토큰(기기) 대상 푸시 알림 전송
     *
     * @param targetToken 푸시 알림을 전송할 FCM 토큰
     * @param title       알림 제목
     * @param body        알림 내용
     */
    public void sendMessageTo(String targetToken, String title, String body) {
        try {
            // Notification 객체 생성
            Notification notification = Notification
                    .builder()
                    .setTitle(title)
                    .setBody(body)
                    .build();

            // 안드로이드용 설정
            AndroidConfig androidConfig = AndroidConfig.builder()
                    .setPriority(AndroidConfig.Priority.HIGH)
                    .build();

            // iOS용 설정
            ApnsConfig apnsConfig = ApnsConfig.builder()
                    .setAps(
                        Aps.builder()
                           .setSound("default")
                           .build()
                    )
                    .build();

            // 전송할 Message 생성
            Message message = Message.builder()
                    .setToken(targetToken)
                    .setNotification(notification)
                    .setAndroidConfig(androidConfig)
                    .setApnsConfig(apnsConfig)
                    .build();

            // 메시지 전송
            String response = FirebaseMessaging.getInstance().send(message);
            System.out.println("Successfully sent message: " + response);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

특징

1. token을 통해 특정 사용자한테 메시지 전송
2. FCM 토큰은 “기기 단위”로 발급받는 것이 일반적 → 여러 계정이 하나의 기기를 공유하는 경우 동일한 토큰이 사용될 가능성이 있음
3. 어플을 설치되어 실행되는 순간 FCM 토큰 발급
4. 보통 “로그인 후” 해당 사용자의 토큰을 서버에 전송 → DB에 사용자의 ID와 토큰을 매핑하는 방식 사용
5. 로그아웃 시, 해당 사용자의 ID - 토큰 매핑을 해제하거나 만료 처리하는 로직 가능
6. 클라이언트측도 FCM Token을 임시 저장하고 상황에 따라 서버로 전송하는 경우가 일반적
7. 메모리나 localStorage등에 담아두었다가 서버로 전송

고려사항

1. 한 사용자가 한 계정으로 여러 기기에서 동시 사용

• 폰, 태블릿, pc 등 동일 계정으로 여러 기기에서 사용하는경우 → 기기마다 토큰 발행
• Member-FcmToken 1:N 매핑
• 모든 기기에서 동일하게 푸시메시지를 받을 수 있게 구현
• 로그아웃 시 해당 기기의 토큰만 db에서 삭제해야 함

2. 하나의 기기에서 여러 계정 사용

• 기기마다 토큰을 발행하기에 서로 다른 계정이 동일한 FCM 토큰을 사용할 가능성이 있음
• 로그아웃 시 db에서 해당 토큰 삭제 (로그아웃 요청 시 클라이언트에서 FCM 토큰을 추가로 넘기게 하여 해당 계정 및 기기의 FCM 토큰을 삭제)

3. 한명의 사용자가 오랫동안 사용하지 않는경우

• FCM 토큰이 테이블에 쌓임 → db성능 저하
• FcmToken 엔티티 필드에 “마지막 로그인” 과 같은 필드 추가
• n개월 이상 미 접속 시 → FCM 토큰 삭제

클라이언트 FCM Token 발급

• 백엔드에서 테스트 코드 작성을 위해 FCM Token이 필요하지만 해당 토큰은 firebase에서 발급해주기 때문에 mock데이터를 만들 수 없음
• 따라서 token 발급을 위해 클라이언트 코드에서 직접 발급이 필요

1. 웹 SDK 설정값

FirebaseConfig

• Firebase 콘솔 → “프로젝트 설정” → “일반” 탭에서 웹 앱 구성 부분에서 JSON 형태로 제공

  {
    "apiKey": "AIzaSyA******",
    "authDomain": "my-project.firebaseapp.com",
    "projectId": "my-project",
    "storageBucket": "my-project.appspot.com",
    "messagingSenderId": "1234567890",
    "appId": "1:1234567890:web:abcdefg12345"
  }
  

vapidKey

• Firebase 콘솔에서 “클라우드 메시징” → “구성” → “Web Push 인증서” → “키 쌍 생성”
• 예시: BGMza-Lw4pEyFJ-HxbXbLaHxdfI-xhF6zUdYaIUJ9-q3kxWBDGConYfYaqaNjxUskLWRYKh4VMlJtay1BwVcCZI
• 해당 문자열을 messaging.getTokne({ vapidKey: "..." })에 작성

→ 해당 값들은 Public 값이므로 firebase-admin-sdk.json파일과는 다르게 하드코딩해도 무방

→ Admin SDK 정보 (서버 비공개) vs Web SDK 정보 (클라이언트 공개)

추후 유지보수를 위해 application-dev.yml에 해당 값 작성

2. notification.html

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <title>FCM Test</title>
  <!-- Firebase SDK -->
  <script src="https://www.gstatic.com/firebasejs/9.17.2/firebase-app.js"></script>
  <script src="https://www.gstatic.com/firebasejs/9.17.2/firebase-messaging.js"></script>
</head>
<body>
  <h1>Firebase Web SDK Test</h1>

  <!-- Thymeleaf JS 치환 -->
  <script th:inline="javascript">
  /*<![CDATA[*/
    var firebaseConfig = {
      apiKey: /*[[${apiKey}]]*/,
      authDomain: /*[[${authDomain}]]*/,
      projectId: /*[[${projectId}]]*/,
      storageBucket: /*[[${storageBucket}]]*/,
      messagingSenderId: /*[[${messagingSenderId}]]*/,
      appId: /*[[${appId}]]*/
    };

    const app = firebase.initializeApp(firebaseConfig);
    const messaging = firebase.messaging();

    messaging.getToken({ vapidKey: 'YOUR_WEB_PUSH_PUBLIC_KEY' })
      .then((token) => {
        if (token) {
          console.log("FCM Token:", token);
        } else {
          console.log("토큰이 없습니다. 알림 권한 설정을 확인하세요.");
        }
      })
      .catch((err) => {
        console.error("FCM 토큰 가져오기 에러:", err);
      });
  /*]]>*/
  </script>
</body>
</html>

model.addAttribute로 값을 동적으로 전송받아 사용가능

or

fetch(...)를 통해 json 반환값으로 값을 전송받아 사용가능 (해당 방법 사용)

문제점 1: firebase-messaging.js:1 Uncaught SyntaxError: Cannot use import statement outside a module (at firebase-messaging.js:1:1)

• Firebase v9 버전부터 도입된 ES Modules(모듈) 기반 문법과 관련
• "Cannot use import statement outside a module"
• "Unexpected token 'export'"등은 브라우저가 일반 <spcipt>태그에서 ES Module 코드를 해석하려고 해서 발생하는 에러

Firebase v9

1. Modular 방식 (ES Modules)
   • import { initializeApp } from 'firebase/app'식으로 import 구문 사용
   • <script type="module">환경에서만 동작
2. Compatibility(compat) 방식 (v8 스타일)
   • <script src=".../firebase-app-compat.js"></script> 처럼 기존 v8 문법(firebase.initializeApp(...))을 그대로 사용할 수 있도록 호환 레이어 제공

→ 현재 v8 스타일 문법이므로 “compat 버전”으로 해결

<!-- 기존 -->
<script src="https://www.gstatic.com/firebasejs/9.17.2/firebase-app.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.17.2/firebase-messaging.js"></script>

<!-- 변경: compat 버전 -->
<script src="https://www.gstatic.com/firebasejs/9.17.2/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.17.2/firebase-messaging-compat.js"></script>

• Modular 방식으로 고도화하기 (선택)

  Firebase v9 Modular 문법을 쓰고 싶다면, 아래처럼 type="module" 스크립트를 사용하고,

  코드도 import 문법으로 작성해야 합니다.

  2.1. 예시 (Modular)

  html
  복사
  <!-- index.html -->
  <script type="module">
    import { initializeApp } from "https://www.gstatic.com/firebasejs/9.17.2/firebase-app.js";
    import { getMessaging, getToken } from "https://www.gstatic.com/firebasejs/9.17.2/firebase-messaging.js";
  
    const firebaseConfig = {
      // ...
    };
    const app = initializeApp(firebaseConfig);
    const messaging = getMessaging(app);
  
    getToken(messaging, { vapidKey: '...' })
      .then(token => {
        console.log("FCM Token:", token);
      })
      .catch(err => {
        console.error("Token error:", err);
      });
  </script>

  • 이 방식은 jQuery 같은 라이브러리 사용 시 모듈 스코프와의 충돌에 주의해야 합니다.
  • 또한 브라우저가 ES Modules를 지원해야 합니다. (현대 브라우저 대부분 지원)

문제점 2: firebase-messaging-sw.js 파일 누락

• Firebase Cloud Messaging(웹 푸시) 에서는 브라우저 푸시를 수신하기 위해 Service Worker 파일이 필요
• 브라우저가 http://localhost:8080/firebase-messaging-sw.js 에서 HTTP 200 OK 로 해당 파일을 내려받음
• 기본적으로 messaging.getToken()호출 시 firebase-messaging-sw.js라는 파일을 현재 호스트의 루트 경로에서 찾음
  • 예: https://example.com/firebase-messaging-sw.js
  • 로컬 개발: http://localhost:8080/firebase-messaging-sw.js

→ 따라서 firebase-messaging-sw.js파일을 정적(/static) 경로로 서빙해야됨

→ 또한 Spring Boot에서 403 오류가 발생하지 않도록 Spring Security에서 permitAll 설정

• 기본 경로는 /root/firebase-messaging-sw.js (/resources/static/firebase-messaging-sw.js)
• 수동 등록하는 경우 경로 상관X navigator.serviceWorker.register(...)호출로 수동 등록 가능
  • 하지만 root경로 (/static/firebase-messaging-sw.js)가 아닌경우 scope를 설정해줘야하는 문제 및 install 후 activate 로 가지못하는 문제가 발생하기도 함
  • 따라서 root경로 배치가 더 안정적임

문제점 3: 처음 페이지 로드 시 Service Worker(firebase-messaging-sw.js)가 완전히 등록/활성 되지 않음

• 첫 페이지 로드 시 firebase-messaging-sw.js 파일이 완전히 등록/활성화 되지 않아 messaging.getToken()메서드가 제대로 동작 X

• 이후 두번째부터는 해당 파일이 잘 등록되어있어 토큰 발급 가능

• 수동으로 Service Worker 등록 후 messaging.getToken()에 전달

  navigator.serviceWorker.register('/firebase-messaging-sw.js')
    .then((registration) => {
      const messaging = firebase.messaging();
      return messaging.getToken({
        vapidKey: VAPID_KEY,
        serviceWorkerRegistration: registration
      });
    })
    .then((token) => {
      console.log("토큰:", token);
    })
    .catch(err => {
      console.error("토큰 획득 에러:", err);
    });

3. CI/CD과정에서 동적으로 firebase-messaging-sw.js파일 생성

🙋‍♂️ 담당자

• 백엔드: @Chuseok22
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

@Chuseok22 오호 잘 읽고갑니다

그러면 메시지를 publish하는 방식은 어떤식으로 코드를 짜야하나요?

[Chuseok22]

@Chuseok22 오호 잘 읽고갑니다

그러면 메시지를 publish하는 방식은 어떤식으로 코드를 짜야하나요?

알림 발송이 필요한 로직에서 해당 사용자에게 알림을 전송하면 됩니다
예를들어 A라는 사용자가 작성한 글에 좋아요가 증가하여 알림을 보내야하는경우를 가정합니다. 이때 좋아요 증가 로직은 LikeService클래스의 processLikeRequest라는 메서드에서 진행되는데, 좋아요를 증가시킴과 동시에 A라는 사용자의 FCM 토큰을 데이터베이스에서 찾아서 알림을 발송하면 됩니다.

[Chuseok22]

관리자가 공지사항을 작성하여 모든 사용자에게 새로운 공지사항이 등록되었습니다.라는 알림을 전송할때도 과정은 동일합니다
AdminApiSerivce클래스의 saveNoticePost메서드에서 공지사항을 등록함과 동시에 모든 사용자에게 알림을 보내는 sendNotificationToAll메서드를 호출하면 됩니다