Firebase FCM: Node.js에서 여러 기기에 동시에 메시지 보내는 방법 (Multicast)

Firebase Cloud Messaging(FCM)을 사용하다 보면 한 명의 사용자가 아닌, 여러 사용자에게 동시에 알림을 보내야 할 때가 있습니다. Node.js 환경에서 Admin SDK를 사용하여 효율적으로 다중 전송을 구현하는 방법을 정리해 보겠습니다.

---

1. 어떤 방식을 사용해야 할까?

FCM에서 여러 토큰으로 메시지를 보내는 방법은 크게 두 가지입니다.

1. Multicast (추천): 특정 토큰 리스트(최대 500개)를 지정하여 전송. 개인화된 그룹 알림에 적합.
2. Topic Messaging: 특정 주제를 구독한 불특정 다수에게 전송. 전체 공지사항에 적합.

오늘은 가장 많이 쓰이는 Multicast(멀티캐스트) 방식을 살펴보겠습니다.

---

2. 필수 패키지 설치

먼저 Firebase Admin SDK가 프로젝트에 설치되어 있어야 합니다.

npm install firebase-admin

---

3. Node.js 전송 코드 예제

Firebase Admin SDK 버전 10 이상에서는 sendEachForMulticast() 메서드 사용을 권장합니다.

const admin = require('firebase-admin');

// 서비스 계정 키 설정 (Firebase 콘솔에서 다운로드)
const serviceAccount = require('./path/to/your-service-account-key.json');

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

async function sendMulticastMessage() {
  // 1. 수신할 기기들의 토큰 배열 (한 번에 최대 500개)
  const registrationTokens = [
    'USER_TOKEN_1',
    'USER_TOKEN_2',
    'USER_TOKEN_3',
    // ... 추가 토큰
  ];

  // 2. 메시지 내용 구성
  const message = {
    notification: {
      title: '🎁 깜짝 이벤트 도착!',
      body: '지금 앱을 확인하고 선물을 받아가세요.'
    },
    // 중요: 'token'이 아니라 'tokens' (배열 형식)
    tokens: registrationTokens, 
  };

  try {
    // 3. 메시지 전송
    const response = await admin.messaging().sendEachForMulticast(message);
    
    console.log(`성공적으로 보낸 메시지: ${response.successCount}개`);
    console.error(`전송 실패한 메시지: ${response.failureCount}개`);

    // 4. 실패한 토큰 처리 (DB 정리 등)
    if (response.failureCount > 0) {
      const failedTokens = [];
      response.responses.forEach((resp, idx) => {
        if (!resp.success) {
          failedTokens.push(registrationTokens[idx]);
          // 여기서 유효하지 않은 토큰을 DB에서 삭제하는 로직을 넣으면 좋습니다.
          console.error(`실패 사유 (${registrationTokens[idx]}):`, resp.error.message);
        }
      });
    }
  } catch (error) {
    console.error('전송 중 치명적 오류 발생:', error);
  }
}

sendMulticastMessage();

---

4. 구현 시 주의사항 (꿀팁)

✅ 500개 제한 준수

sendEachForMulticast는 한 번 요청에 최대 500개의 토큰만 처리할 수 있습니다. 만약 보낼 대상이 1,000명이라면 500개씩 리스트를 나누어(Chunk) 두 번 호출해야 합니다.

✅ 실패한 토큰 관리

사용자가 앱을 삭제하거나 토큰이 만료되면 전송 실패가 발생합니다. response.responses를 순회하며 에러가 발생한 토큰은 데이터베이스에서 삭제하거나 업데이트해야 전송 효율을 높일 수 있습니다.

✅ 보안 주의

serviceAccountKey.json 파일은 서버의 모든 권한을 가진 중요한 파일입니다. 절대로 GitHub 같은 공개 저장소에 올리지 마세요! .gitignore에 등록하거나 환경 변수로 관리하는 것이 안전합니다.

---

마치며

Node.js와 Firebase Admin SDK를 사용하면 대량의 푸시 알림도 매우 간단하게 처리할 수 있습니다.

 

수천 명 이상의 대규모 전송이 필요하다면 토큰 관리 부담이 적은 Topic 방식도 고려해 보시기 바랍니다!