README.ko.md

firebase-kmp

Firebase API를 Kotlin Multiplatform(Android/Apple/JVM) 공통 코드에서 사용할 수 있도록 래핑한 오픈소스 라이브러리입니다.

언어:

• 영어: README.md
• 한국어 (이 문서)

왜 firebase-kmp인가?

• KMP 공유 코드에서 Firebase API를 Firebase 스타일로 사용할 수 있습니다.
• Android, Apple, JVM 동작을 가능한 범위에서 일관되게 맞춥니다.
• JVM 타겟을 제공하는 모듈에서 서버 사이드 워크플로우를 지원합니다.

모듈 매트릭스

모듈	Firebase 제품군	현재 범위	Public API 커버리지	상태
firebase-common	Core	앱 초기화, 앱 인스턴스, 옵션, 앱 레지스트리	21 / 25 = 84.0%	partial
firebase-message	Cloud Messaging	topic/token API (Android/Apple 전용, JVM 미지원)	6 / 18 = 33.3%	partial
firebase-storage	Cloud Storage	스토리지 레퍼런스 API + 바이트/다운로드/삭제 (참고 사항 확인)	13 / 31 = 41.9%	partial

타겟

타겟	지원
Android	Yes
Apple (ios*, macos*, tvos*, watchos*)	Yes
JVM	Yes

참고:

• visionOS 타겟은 Firebase SDK 호환성과 KMP interop 안정성 검증 후 확장 예정입니다.
• firebase-message 모듈은 현재 Android/Apple 타겟만 지원합니다.

API 호환 커버리지 (업데이트: 2026-02-16)

목표:

• KMP 기준 Firebase API 호환 커버리지 100%
• 지원 모듈별 Public API 커버리지 100%

커버리지 산정 방식:

• 제품군 커버리지 = 구현된 Firebase 제품군 수 / 목표 제품군 수
• Public API 커버리지 = 구현된 public API 수 / 목표 public API 수 (제품군별, 플랫폼별)
• 구현 깊이 상태 = not started, partial, near parity, parity

현재 스냅샷:

• 제품군 커버리지: 3 / 18 = 16.7%
• Public API 카탈로그: docs/public-api/README.md

모듈	커버리지	카탈로그
firebase-common	21 / 25 = 84.0%	docs/public-api/firebase-common.md
firebase-message	6 / 18 = 33.3%	docs/public-api/firebase-message.md
firebase-storage	13 / 31 = 41.9%	docs/public-api/firebase-storage.md

목표 제품군 (18개):

• Core, Cloud Messaging, Cloud Storage, Authentication, Cloud Firestore, Realtime Database, Cloud Functions, Analytics, Crashlytics, Performance Monitoring, Remote Config, App Check, In-App Messaging, Dynamic Links, Installations, ML, Data Connect, Vertex AI in Firebase

설치

Maven 좌표 (버전 예시: 0.0.1):

dependencies {
    implementation("io.github.big-gates:firebase-common:0.0.1")
    implementation("io.github.big-gates:firebase-message:0.0.1")
    implementation("io.github.big-gates:firebase-storage:0.0.1")
}

Quick Start (JVM)

1) Firebase 초기화

import com.biggates.firebase.common.Firebase
import com.biggates.firebase.common.FirebaseOptions
import com.biggates.firebase.common.PlatformContext

fun initFirebaseOnJvm() {
    Firebase.initializeApp(
        context = PlatformContext(),
        options = FirebaseOptions(
            applicationId = "your-app-id",
            apiKey = "your-api-key",
            projectId = "your-project-id",
            storageBucket = "your-project-id.appspot.com",
            serviceAccountPath = "/absolute/path/service-account.json" // JVM 전용
        )
    )
}

2) JVM에서 Messaging

firebase-message는 현재 JVM 타겟 API를 제공하지 않습니다. Messaging API는 Android/Apple 타겟에서 사용하세요.

3) Storage (레퍼런스 + 바이트)

import com.biggates.firebase.common.Firebase
import com.biggates.firebase.storage.storage

suspend fun storageJvmSample() {
    val storage = Firebase.storage

    val ref = storage.reference("images/profile.png")
    ref.putBytes("hello-storage".encodeToByteArray())
    val bytes = ref.getBytes(maxDownloadSizeBytes = 1024 * 1024)
    val downloadUrl = ref.getDownloadUrl()
    ref.delete()

    val gsRef = storage.referenceFromUrl("gs://your-project-id.appspot.com/images/profile.png")
    val childRef = gsRef.child("thumb.png")

    // Storage Emulator
    storage.useEmulator("127.0.0.1", 9199)
}

중요 참고사항

• JVM에서 initializeApp(context)만 호출하면 실패합니다. initializeApp(context, options)를 사용해야 합니다.
• JVM에서 serviceAccountPath를 생략하면 ADC(Application Default Credentials)를 사용합니다.
• firebase-message는 현재 JVM 타겟을 지원하지 않습니다.
• JVM 기본 Firebase.storage 사용 시 storageBucket 설정이 필요합니다.
• StorageReference.putBytes(...)는 현재 iOS 타겟 구현이 진행 중입니다.

빌드 검증

./gradlew :firebase-common:check :firebase-message:check :firebase-storage:check
./gradlew :firebase-common:compileKotlinJvm :firebase-storage:compileKotlinJvm

프로젝트 문서

• Public API 카탈로그: docs/public-api/README.md
• 저장소 에이전트 가이드: AGENTS.md
• docs/agents/firebase-common.md
• docs/agents/firebase-message.md
• docs/agents/firebase-storage.md