1. 목적
Firebase Cloud Messaging(FCM) 기반 푸시 알림을 통해 앱 미사용 중인 사용자에게도 중요한 소식과 콘텐츠 업데이트를 전달한다.
사용자 설정에 따라 수신 여부를 제어할 수 있으며, 발송 이력을 기록하여 관리한다.
2. FCM 토큰 및 기기 관리
2-1. UserDevice 모델
사용자의 기기 정보와 FCM 토큰을 관리한다.
| 필드 | 타입 | 설명 |
|---|
user | FK(User) | 기기 소유자 |
device_id | CharField(255) | 기기 고유 ID (유니크) |
device_type | CharField(50) | 기기 플랫폼 (ios, android) |
device_model | CharField(100) | 기기 모델명 |
app_version | CharField(20) | 앱 버전 |
timezone | CharField(50) | 사용자 타임존 (예: Asia/Seoul) |
fcm_token | CharField(500) | FCM 푸시 토큰 (인덱싱) |
is_active | BooleanField | 기기 활성 여부 |
push_enabled | BooleanField | OS 알림 권한 허용 여부 |
last_active | DateTimeField | 마지막 활동 시각 (자동 갱신) |
2-2. 기기 등록 프로세스
- 앱 시작 시 Firebase 초기화 후 FCM 토큰을 발급받는다.
- 기기 정보(device_id, device_type, device_model, app_version, timezone, push_enabled)와 함께 서버에 등록한다.
- 앱이 포그라운드로 복귀할 때마다 OS 알림 권한 상태를 확인하여 서버와 동기화한다.
3. 사용자 알림 설정
사용자 모델(User)에서 관리되는 푸시 알림 관련 설정이다.
| 필드 | 기본값 | 설명 |
|---|
push_notification_enabled | true | 푸시 알림 마스터 토글 |
notification_marketing | false | 이벤트 및 소식 알림 수신 여부 |
notification_bookmark | true | 관심 콘텐츠(북마크) 알림 수신 여부 |
알림 설정 UI
프론트엔드에서 다음과 같은 설정 화면을 제공한다.
| UI 항목 | 연동 필드 | 설명 |
|---|
| 알림 수신 (OS 설정 연동) | OS 권한 | OS 알림 권한이 꺼져 있으면 "켜기 >" 버튼 표시, 탭 시 OS 설정으로 이동 |
| 이벤트 및 소식 알림 | notification_marketing | 팬타 소식, 이벤트/프로모션 관련 푸시 수신 토글 |
| 관심 콘텐츠 알림 | notification_bookmark | 북마크/열람 콘텐츠 업데이트 푸시 수신 토글 |
- OS 푸시 권한이 꺼져 있으면 모든 토글이 비활성화(투명도 40%) 처리된다.
- 설정 변경 시 서버에 즉시 반영된다.
4. 푸시 메시지 템플릿
4-1. PushMessageTemplate 모델
다국어 지원 모델(TranslatableModel)로 관리되며, push_type별로 다국어 제목과 본문을 정의한다.
| 필드 | 타입 | 설명 |
|---|
push_type | CharField(30) | 푸시 유형 (아래 표 참조) |
is_active | BooleanField | 템플릿 활성 여부 |
title (다국어) | CharField(200) | 푸시 제목 |
body (다국어) | TextField | 푸시 본문 |
created_at | DateTimeField | 생성 시각 |
4-2. push_type 목록
| push_type | 표시명 | 설명 |
|---|
trial_reminder | 체험 리마인더 | 체험판 사용자에게 구독 유도 리마인더 |
sticker_release | 찜 스티커 출시 | 북마크한 콘텐츠의 스티커 출시 알림 |
weekly_update | 주간 업데이트 | 주간 신규 콘텐츠 요약 알림 |
inactive_routine | 미접속 루틴 | 장기 미접속 사용자 재방문 유도 |
brand_news | 브랜드 뉴스 | 팬타 브랜드 관련 소식 |
event_promotion | 이벤트/프로모션 | 이벤트 및 프로모션 안내 |
feature_update | 기능 업데이트 | 신규 기능 출시 안내 |
5. 푸시 발송 로그
5-1. PushLog 모델
모든 푸시 발송 내역을 기록하여 추적 및 분석에 활용한다.
| 필드 | 타입 | 설명 |
|---|
user | FK(User) | 수신 사용자 |
push_type | CharField(30) | 발송된 푸시 유형 |
template | FK(PushMessageTemplate, nullable) | 사용된 템플릿 (삭제 시 SET_NULL) |
sent_at | DateTimeField | 발송 시각 (자동 기록) |
status | CharField(10) | 발송 결과 (success 또는 failed) |
5-2. DB 인덱스
| 인덱스 필드 | 용도 |
|---|
user, push_type, -sent_at | 사용자별 푸시 유형별 발송 이력 조회 |
user, -sent_at | 사용자별 전체 발송 이력 조회 |
6. 관리자 푸시 발송
관리자 전용 발송 기능으로, 특정 사용자 그룹에 수동으로 푸시 알림을 발송할 수 있다.
| 항목 | 내용 |
|---|
| 경로 | /qth56szk7i/send-push/ |
| 접근 권한 | 관리자(admin) 전용 |
| 기능 | 대상 사용자 선택, 템플릿 기반 또는 직접 입력 방식으로 푸시 발송 |
7. 프론트엔드 푸시 처리
7-1. 앱 상태별 처리
| 앱 상태 | 처리 방식 |
|---|
| 포그라운드 | FCM 메시지 수신 시 알림 배지(레드닷) 상태만 갱신, 시스템 알림 표시 없음 |
| 백그라운드 | FCM 백그라운드 핸들러에서 Firebase 초기화 후 시스템 알림 표시 |
| 종료 상태 | 푸시 클릭으로 앱이 열리면 스플래시 완료 후 대기 메시지를 처리하여 해당 화면으로 이동 |
7-2. 딥링크 연동 (푸시 클릭 시 네비게이션)
푸시 메시지의 data 페이로드에 포함된 정보를 기반으로 화면을 이동한다.
스케줄 푸시 (push_type 기반)
| push_type | 이동 대상 |
|---|
sticker_release | 도서 상세 (target_id 있을 경우) 또는 홈 |
weekly_update | 도서 상세 (target_id 있을 경우) 또는 홈 |
inactive_routine | 홈 |
trial_reminder | 홈 |
인앱 트리거 푸시 (type + action_type 기반)
| type | action_type | 이동 대상 |
|---|
user_content | book_detail | 도서 상세 |
penta_news | event_news | 소식 상세 |
penta_news | event_event | 이벤트 탭 |
penta_news | inquiry_detail | 고객지원 > 1:1 문의 상세 |
- 미인증 상태에서는 푸시 네비게이션을 스킵한다.
- 모든 푸시 클릭 이벤트는 Firebase Analytics에
push_click 이벤트로 기록된다.
7-3. 앱 복귀 시 권한 동기화
앱이 백그라운드에서 포그라운드로 복귀할 때 _PushPermissionObserver가 OS 알림 권한 상태를 확인하여 서버의 push_enabled 값과 동기화한다.
8. 발송 정책 요약
| 항목 | 정책 |
|---|
| 발송 채널 | Firebase Cloud Messaging (FCM) |
| 지원 플랫폼 | iOS, Android |
| 토큰 갱신 | 앱 시작 시 매회 서버에 등록/갱신 |
| 언어 설정 | 사용자 앱 설정 언어 기준 다국어 템플릿 적용 |
| 수신 제어 | OS 권한 + 앱 내 설정(마케팅/북마크) 조합으로 결정 |
| 발송 이력 | PushLog에 전량 기록 (성공/실패 구분) |
| 분석 연동 | 푸시 클릭 시 Firebase Analytics 이벤트 자동 기록 |