21-push-setup-google
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
02 资源文件 2
- 参考文档agents/openai.yaml121 B
- 参考文档references/private-data.md5.1 KB
03 SKILL.md 正文
21-push-setup-google — Google Push (FCM Android) Setup
Status: ACTIVE AppliesTo: v10
문서 경계 (Scope)
- 이 문서는 Android 푸시 알림 인프라를 새 프로젝트에 셋업하는 실행 가이드 정본이다.
- 포함: Firebase 프로젝트 Android 앱 등록, google-services.json, Gradle 설정, AndroidManifest, NotificationChannel
- 비포함: PushManager 런타임 구현(→
10), Provider 구현 상세(→12)
A. 사전 요구사항 (Prerequisites)
A1. 필요 도구
| 도구 | 용도 |
|---|---|
| Firebase Console | Android 앱 등록 + FCM 활성화 |
| Unity Editor | Android 빌드 설정 |
A2. 필요 정보
| 항목 | 예시 | 설명 |
|---|---|---|
{PACKAGE_NAME} |
com.devian.framework |
Android 패키지명 |
{FIREBASE_PROJECT_ID} |
devian-framework-example |
Firebase 프로젝트 ID |
B. Firebase Console — Android 앱 등록
- Firebase Console → 프로젝트 → 앱 추가 → Android
- Package name:
{PACKAGE_NAME} google-services.json다운로드
C. Unity 프로젝트 설정
C1. google-services.json
- B에서 다운로드한
google-services.json을 Unity 프로젝트에 배치 - 경로:
Assets/Plugins/Android/google-services.json - Unity 빌드 시 Android 프로젝트에 자동 복사됨
C2. Firebase Unity SDK
Firebase Unity SDK패키지에서FirebaseMessaging.unitypackage임포트- 또는 UPM:
com.google.firebase.messaging
C3. Custom Gradle 설정 (Unity)
Unity → Player Settings → Android → Publishing Settings:
- Custom Main Gradle Template 활성화
- Custom Launcher Gradle Template 활성화
Firebase Unity SDK가 자동으로 google-services 플러그인과 dependencies를 주입한다. 수동 Gradle 수정이 필요한 경우에만 아래를 참조.
C4. AndroidManifest — POST_NOTIFICATIONS 권한 (Android 13+)
<!-- Assets/Plugins/Android/AndroidManifest.xml -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
Android 12 이하에서는 이 권한이 자동 부여된다. 선언해도 무해.
C5. NotificationChannel (Android 8+)
Android 8(API 26)부터 알림 채널이 필수다.
PushProviderGoogle에서 앱 시작 시 기본 채널을 생성한다.
채널 설정:
| 항목 | 값 |
|---|---|
| Channel ID | devian_push_default |
| Channel Name | Push Notifications |
| Importance | HIGH |
채널 ID/Name은 프로젝트별로 변경 가능. Provider 내부에서 하드코딩하지 않고 설정 가능하게 구성 권장.
D. FCM 토픽 발송 (Firebase Console)
서버 토큰 등록/타겟 발송은 사용하지 않는다. 모든 원격 푸시는 토픽 기반 발송만 사용한다.
D1. FCM v1 API 활성화
- Google Cloud Console → Firebase Cloud Messaging API → 사용 설정
- 이미 Firebase 프로젝트에서 활성화된 경우 생략
D2. 토픽 발송 방법
- Firebase Console: Messaging → 새 캠페인 → 토픽 대상 지정 → 발송
- Firebase Admin SDK (기존 Functions에서 필요 시):
import { getMessaging } from "firebase-admin/messaging";
await getMessaging().send({
topic: topicId,
notification: { title: "...", body: "..." },
data: { /* custom payload */ }
});
토큰 기반 발송(
token: userFcmToken)은 사용하지 않는다. Firebase Functions/Firestore에 토큰을 저장하지 않는다.
E. 검증 체크리스트
| # | 항목 | 방법 | 기대 결과 |
|---|---|---|---|
| 1 | google-services.json | Unity 빌드 성공 | 에러 없음 |
| 2 | FCM API 활성화 | GCP Console → API 목록 | Firebase Cloud Messaging API 활성 |
| 3 | 토큰 획득 | 기기에서 앱 실행, PushManager.InitializeAsync |
FCM 토큰 로그 출력 |
| 4 | 원격 푸시 수신 | Firebase Console → Messaging → 테스트 메시지 전송 | 기기에서 알림 수신 |
| 5 | 토픽 푸시 수신 | 토픽 구독 후 토픽 발송 | 기기에서 알림 수신 |
| 6 | POST_NOTIFICATIONS | Android 13 기기에서 권한 팝업 | 권한 요청 다이얼로그 표시 |
F. 트러블슈팅
F1. 토큰 획득 실패
원인: google-services.json 누락 또는 패키지명 불일치
해결: B에서 올바른 패키지명으로 재다운로드
F2. 알림 미수신 (Android 13+)
원인: POST_NOTIFICATIONS 런타임 권한 미요청 또는 거부
해결: PushProviderGoogle에서 권한 요청 로직 확인 (→ 12)
F3. 알림 미표시 (Android 8+)
원인: NotificationChannel 미생성
해결: 앱 시작 시 devian_push_default 채널 생성 확인 (→ 12)
F4. FCM v1 API 비활성
원인: 레거시 서버 키 사용 또는 API 미활성화 해결: D1 실행. FCM v1 HTTP API만 사용한다 (레거시 서버 키 금지).
Related
- 12-push-provider-google — 런타임 Provider 구현
- 10-push-manager — PushManager 설계
- 03-ssot — Push 시스템 SSOT