# Firebase SDK 초기화

Firebase BoM과 firebase-analytics 의존성을 추가하고 Application/AppDelegate에서 Firebase를 초기화한 뒤 빌드로 연동을 확인하는 절차.

- 카테고리: Firebase
- 소요 시간: 약 9분
- 난이도: 중간
- 업데이트: 2026.06.16
- 원문: /wiki/playbook/firebase-checklist/how-to-initialize-firebase-sdk

## 목차

- [이 문서의 목적](#purpose)
- [1단계 · Android Gradle 의존성](#step-1)
- [2단계 · Android 초기화](#step-2)
- [3단계 · iOS 의존성 설치](#step-3)
- [4단계 · iOS 초기화](#step-4)
- [5단계 · 초기화 확인](#step-5)
- [참고 링크](#references)
- [자주 묻는 질문](#faq)

이 문서는 앞 글에서 등록한 Firebase 앱에 Android·iOS SDK를 설치하고, 앱 실행 시 한 번 Firebase를 초기화하는 절차를 다룹니다. 이벤트 전송과 WebView 연동은 SDK가 정상 초기화된 뒤 이어지는 후속 작업입니다. 설정 파일(`google-services.json`, `GoogleService-Info.plist`) 배치는 완료되어 있다고 가정합니다.

> **이 문서 핵심**
>
> - Android `app/google-services.json`, iOS `GoogleService-Info.plist` 배치가 먼저 끝나 있어야 합니다.
>
> - Analytics만 쓰는 경우 핵심 의존성은 Android `firebase-analytics`, iOS `FirebaseAnalytics`입니다.
>
> - 완료 후 앱 실행 시 Firebase 세션과 자동 수집 이벤트(`session_start`, `first_open` 등)가 전송됩니다.

> **정보**
>
> Firebase는 버전을 개별 지정하는 대신 **Firebase BoM(Bill of Materials)**을 권장합니다. BoM 한 줄만 버전을 명시하면 `firebase-analytics` 같은 개별 라이브러리는 버전 없이 선언해도 BoM이 호환 버전을 맞춰 줍니다.

## 1단계. Android Gradle 의존성과 플러그인 추가

Google Services Gradle 플러그인은 `google-services.json`을 읽어 빌드에 Firebase 설정을 주입합니다. 루트와 앱 모듈 양쪽에 플러그인을 선언해야 합니다. 아래는 버전 카탈로그 없이 직접 선언하는 예시입니다.

**settings.gradle.kts · 또는 프로젝트 build.gradle.kts**
```kotlin
plugins {
    // Google Services 플러그인 (버전은 최신 안정 버전 사용)
    id("com.google.gms.google-services") version "4.4.4" apply false
}
```

앱 모듈에서 플러그인을 적용하고 BoM과 Analytics 의존성을 추가합니다.

**app/build.gradle.kts**
```kotlin
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.gms.google-services")
}

dependencies {
    // Firebase BoM — 이 한 줄로 개별 라이브러리 버전을 정렬합니다.
    implementation(platform("com.google.firebase:firebase-bom:34.14.1"))

    // Analytics (버전은 BoM이 관리하므로 명시하지 않습니다.)
    implementation("com.google.firebase:firebase-analytics")
}
```

> **주의**
>
> BoM 34.x 이후에는 `firebase-analytics-ktx` 같은 KTX 모듈을 새로 추가하지 않습니다. Kotlin 프로젝트도 `com.google.firebase:firebase-analytics` 기본 모듈과 `FirebaseAnalytics` API를 사용합니다. BoM 34.x 의존성이 Kotlin 2.2 메타데이터를 포함할 수 있으므로, Kotlin Gradle 플러그인이 오래된 프로젝트라면 Kotlin 2.2 계열로 함께 올린 뒤 빌드합니다.

광고 ID(AD_ID) 권한은 캠페인 어트리뷰션을 함께 쓸 때 필요합니다. 순수 분석만이면 생략할 수 있습니다.

**AndroidManifest.xml**
```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 광고 ID 기반 어트리뷰션이 필요할 때만 -->
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
```

![Firebase 콘솔 'Firebase SDK 추가' 단계의 Android Gradle 설정 안내 화면. Kotlin DSL(build.gradle.kts) 옵션이 선택되어 있고, 루트 수준 build.gradle.kts 에 추가할 google-services Gradle 플러그인 의존성(com.google.gms.google-services 버전 4.4.4) 코드 블록이 빨간 박스로 강조되어 있다.](/wiki-assets/playbook/how-to-initialize-firebase-sdk/01-android-gradle-sync.png)

> **화면 1.** 루트 수준 `build.gradle.kts`에 google-services 플러그인 의존성을 추가하고 Gradle Sync를 실행.

## 2단계. Android에서 Firebase 초기화

`google-services` 플러그인을 적용하면 `FirebaseApp.initializeApp()`이 `ContentProvider`를 통해 앱 시작 시 자동 호출되므로, 별도 초기화 코드 없이도 동작합니다. 다만 이벤트 로깅에 쓸 `FirebaseAnalytics` 인스턴스는 한 번 획득해 보관해 두는 것이 좋습니다. Application의 `onCreate`가 적절한 위치입니다.

**BaseApplication.kt**
```kotlin
import android.app.Application
import com.google.firebase.analytics.FirebaseAnalytics

class BaseApplication : Application() {
    lateinit var firebaseAnalytics: FirebaseAnalytics
        private set

    override fun onCreate() {
        super.onCreate()
        // FirebaseApp 자동 초기화 이후, Analytics 인스턴스를 확보합니다.
        firebaseAnalytics = FirebaseAnalytics.getInstance(this)
    }
}
```

> **정보**
>
> 디버그 빌드에서 DebugView로 즉시 확인하려면 ADB로 디버그 모드를 켭니다. 이 설정은 검증 글에서 다시 다룹니다.

**Android DebugView 활성화**
```bash
adb shell setprop debug.firebase.analytics.app kr.hurdlers.appbuilder
```

## 3단계. iOS SDK 의존성 설치

iOS는 Swift Package Manager(SPM) 또는 CocoaPods 중 하나를 선택합니다. 신규 프로젝트라면 SPM을 권장합니다. Xcode의 File → Add Package Dependencies에서 Firebase iOS SDK 저장소를 추가하고 `FirebaseAnalytics` 제품을 앱 타겟에 포함합니다.

**SPM 패키지 URL**
```text
https://github.com/firebase/firebase-ios-sdk
```

CocoaPods 기반 프로젝트라면 `Podfile`에 추가한 뒤 `pod install`을 실행하고 `.xcworkspace`로 엽니다.

**Podfile**
```ruby
target 'YourAppTarget' do
  use_frameworks!
  pod 'FirebaseAnalytics'
end
```

**Terminal**
```bash
pod install
```

![Xcode Swift Package Manager 패키지 추가 설명 이미지. Add Package 화면의 패키지 URL 입력칸에 https://github.com/firebase/firebase-ios-sdk 가 입력되어 빨간 박스로 강조되어 있고, Package Products 목록에서 FirebaseAnalytics 항목과 SampleApp 타겟 선택 영역이 빨간 박스로 강조되어 있다.](/wiki-assets/playbook/how-to-initialize-firebase-sdk/02-ios-spm-add-package.png)

> **화면 2.** iOS SPM에서 `firebase-ios-sdk`를 추가하고 `FirebaseAnalytics` 제품을 앱 타겟에 포함.

## 4단계. iOS에서 Firebase 초기화

앱 실행 시점에 한 번만 `FirebaseApp.configure()`를 호출합니다. UIKit이면 `AppDelegate`의 `didFinishLaunchingWithOptions`, SwiftUI면 App의 `init()`에서 호출합니다.

**AppDelegate.swift (UIKit)**
```swift
import UIKit
import FirebaseCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        FirebaseApp.configure()
        return true
    }
}
```

**YourApp.swift (SwiftUI)**
```swift
import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
    init() {
        FirebaseApp.configure()
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
```

> **주의**
>
> `FirebaseApp.configure()`는 번들 안의 `GoogleService-Info.plist`를 읽습니다. 파일이 타겟 멤버십에 포함되어 있지 않으면 런타임에 크래시하거나 초기화에 실패합니다. 앞 글의 파일 배치 단계를 먼저 확인하세요.

iOS도 디버그 모드를 켜면 DebugView에서 즉시 확인됩니다. Xcode Scheme의 실행 인수에 추가합니다.

**Xcode Scheme · Run · Arguments Passed On Launch**
```text
-FIRDebugEnabled
```

## 5단계. 초기화 정상 동작 확인

앱을 실행하면 Firebase SDK가 초기화 로그를 출력합니다. 빌드만 되는 것과 초기화가 실제로 되는 것은 다르므로 로그로 확인합니다.

**Android logcat 성공 로그 예시**
```text
FA      : App measurement initialized, version: ...
FA      : Tag Manager is not found and thus will not be used
FA      : Setting useService: ...
```

**iOS 콘솔 성공 로그 예시**
```text
[Firebase/Analytics] Firebase Analytics enabled
```

![터미널 화면. adb logcat -d -s FA FA-SVC 명령을 measurement 키워드로 필터링한 결과로, App measurement collection enabled, App measurement enabled for app package(google app id: kr.hurdlers.appbuilder), App measurement initialized version 167000, Tag Manager is not found, Session started 로그가 차례로 출력되어 있다. 가운데의 'I FA : App measurement initialized, version: 167000' 줄이 빨간 박스로 강조되어 있다.](/wiki-assets/playbook/how-to-initialize-firebase-sdk/03-android-fa-log.png)

> **화면 3.** 앱 실행 후 logcat을 `FA` 태그로 필터링하면 `App measurement initialized` 로그로 SDK 초기화가 확인됩니다.

> **완료**
>
> 초기화가 확인되면 다음 단계는 [이벤트 전송](/wiki/playbook/firebase-checklist/how-to-send-firebase-events)입니다. WebView 앱이라면 [WebView 이벤트 연동](/wiki/playbook/firebase-checklist/how-to-connect-firebase-webview-events)도 함께 진행합니다.

## 참고 링크

- [Firebase Android SDK 설정](https://firebase.google.com/docs/android/setup)
- [Firebase iOS SDK 설정](https://firebase.google.com/docs/ios/setup)
- [Firebase Android BoM 설명](https://firebase.google.com/docs/android/learn-more#bom)
- [Analytics 시작하기(Android)](https://firebase.google.com/docs/analytics/get-started?platform=android)
- [Analytics 시작하기(iOS)](https://firebase.google.com/docs/analytics/get-started?platform=ios)

## 자주 묻는 질문

### Android에서 FirebaseApp.initializeApp()을 직접 호출해야 하나요?

일반적으로 필요 없습니다. google-services 플러그인이 추가하는 ContentProvider가 앱 시작 시 자동으로 초기화합니다. 멀티 프로세스 등 특수한 경우에만 수동 호출을 검토합니다.

### BoM 버전과 firebase-analytics 버전을 둘 다 적어야 하나요?

아니요. BoM에만 버전을 적고 firebase-analytics는 버전 없이 선언합니다. 두 곳에 버전을 적으면 의도치 않은 버전 충돌이 생길 수 있습니다.

### iOS에서 configure()를 ViewController에서 호출해도 되나요?

권장하지 않습니다. 앱 시작 시 한 번만 호출되는 위치(AppDelegate 또는 App init)에 둬야 세션과 first_open 기준이 정확합니다.

## Navigation

- [전체 플레이북 Markdown sitemap](/wiki/playbook/sitemap.md)

### Firebase

- [Firebase](/wiki/playbook/firebase-checklist)
- [Firebase 프로젝트·앱 등록](/wiki/playbook/firebase-checklist/how-to-create-firebase-app)
- [Firebase SDK 초기화](/wiki/playbook/firebase-checklist/how-to-initialize-firebase-sdk) (현재 문서)
- [Firebase WebView 이벤트 연동](/wiki/playbook/firebase-checklist/how-to-connect-firebase-webview-events)
- [Firebase 이벤트 전송](/wiki/playbook/firebase-checklist/how-to-send-firebase-events)
- [Firebase User ID·User Property 설정](/wiki/playbook/firebase-checklist/how-to-set-firebase-user-properties)
- [Firebase 연동 검증](/wiki/playbook/firebase-checklist/how-to-verify-firebase-integration)