---
id: pattern-push-notification
title: "Push Notification Pattern"
category: "Pattern_Mobile"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["push notification", "푸시 알림", "FCM", "APNs", "notification"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.84
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "mobile", "push", "notification", "platform-independent"]
raw_sources: ["일반 모바일 공학 지식", "AstraAI/src/integrations/telegram/*, src/features/briefing/* (유사 예)"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[Push Notification Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
푸시 알림은 "서버가 디바이스로 비동기 메시지를 밀어 넣는" 패턴으로, 토큰 수명 관리·전달 보장 없음·사용자 동의·과알림 피로를 다루지 못하면 오히려 이탈을 부른다.

## 🧠 핵심 개념 (Core concepts)
1. **디바이스 토큰:** 앱이 FCM/APNs 토큰 등록, 서버 저장(만료/갱신).
2. **전송:** 서버→게이트웨이(FCM/APNs)→디바이스.
3. **전달 비보장:** best-effort — 중요 데이터는 알림 본문 말고 동기화로.
4. **동의/채널:** 권한 요청, 카테고리별 on/off.
5. **딥링크:** 탭 시 해당 화면으로.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 서버 이벤트를 사용자에게 즉시 알릴 때.
- **사용 조건:** 게이트웨이 연동; 토큰 저장; 사용자 동의.
- **장점:** 재참여, 실시간 알림, 백그라운드 트리거.
- **단점:** 전달 비보장, 토큰 만료, 권한 거부 시 무력, 과알림 피로.
- **대안:** 인앱 알림, 폴링(배터리↑), 이메일/SMS.
- **실패 사례:** 만료 토큰으로 전송 실패; 알림 본문에만 중요 데이터(미수신 시 유실); 과알림으로 권한 철회; 딥링크 없어 탭 후 길 잃음.

## 💻 코드 패턴 (Code patterns)
```text
onAppStart: token = registerForPush(); server.saveToken(userId, token)
server.onEvent: send(FCM/APNs, token, { title, body, data:{deeplink} })  # best-effort
onReceive: showNotification ; onTap: navigate(data.deeplink)
onTokenRefresh: server.updateToken(...)
```
유사 예: AstraAI 의 Telegram 리포트/daily briefing 이 "서버측 이벤트→사용자 채널 푸시" 구조([[Background Task Pattern]] 워처가 트리거). 전달 비보장 가정도 동일.

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
알림을 "전달된다" 고 가정하면 안 된다 — 중요 상태는 서버에 두고 알림은 *유도* 만. 과알림은 가장 흔한 이탈 원인.

## 🛠️ 적용 사례 (Applied in summary)
AstraAI Telegram 알림(리포트/브리핑).

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[Background Task Pattern]], [[API Client Pattern]], [[모바일 개발 가이드]]
- **참조 맥락:** 작은 모델이 알림 기능을 설계할 때 참조.

## 📚 출처 (Sources)
- [S1] 일반 푸시(FCM/APNs) 지식
- [S2] AstraAI/src/integrations/telegram/*, features/briefing/* — 유사 예

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
