Firebase Crashlytics 설정 방법 (Swift / iOS)
iOS 앱을 운영하다 보면 실제 사용자 환경에서 발생하는 오류를 빠르게 파악하는 것이 중요하다. 특히 테스트 환경에서는 재현되지 않지만, 배포 후 특정 기기나 특정 OS 버전에서만 발생하는 크래시는 일반 로그만으로 원인을 찾기 어렵다.
이럴 때 유용한 도구가 바로 Firebase Crashlytics다. Crashlytics를 적용하면 앱에서 발생한 크래시를 수집하고, 어떤 화면이나 어떤 코드 흐름에서 문제가 발생했는지 좀 더 빠르게 확인할 수 있다.
Firebase Crashlytics란?
Firebase Crashlytics는 앱에서 발생한 비정상 종료 정보를 수집하고, 이를 Firebase 콘솔에서 확인할 수 있게 도와주는 서비스다. 단순히 크래시 발생 여부만 보여주는 것이 아니라, 어떤 버전에서 문제 빈도가 높았는지, 어떤 기기와 OS 조합에서 많이 발생했는지 등을 분석하는 데 도움이 된다.
특히 iOS에서는 dSYM 업로드가 제대로 되어 있어야 크래시 로그가 사람이 읽을 수 있는 함수명과 코드 흐름으로 변환된다. 그래서 Crashlytics 설정은 단순히 SDK 추가로 끝나는 것이 아니라, 초기화와 빌드 스크립트 설정까지 함께 확인하는 것이 중요하다.
Crashlytics 설정 전에 준비할 것
Firebase Crashlytics를 iOS 프로젝트에 적용하려면 먼저 Firebase 프로젝트와 iOS 앱이 Firebase 콘솔에 등록되어 있어야 한다. 또한 Apple 플랫폼용 Firebase SDK를 프로젝트에 추가해야 한다.
- Firebase 프로젝트 생성
- iOS 앱 등록
- GoogleService-Info.plist 추가
- Firebase SDK 설치
- 앱 시작 시 Firebase 초기화
- dSYM 업로드용 Run Script 확인
1. Firebase 프로젝트에 iOS 앱 등록하기
먼저 Firebase 콘솔에서 프로젝트를 만들고, iOS 앱을 등록한다. 앱 등록 시에는 보통 번들 식별자(Bundle Identifier)를 입력해야 한다. 프로젝트 등록이 끝나면 GoogleService-Info.plist 파일을 내려받을 수 있다.
이 파일은 앱과 Firebase 프로젝트를 연결하는 설정 파일이므로, 반드시 현재 사용 중인 앱 타깃에 포함되도록 추가해야 한다.
예: com.example.myapp2. GoogleService-Info.plist 파일 추가하기
다운로드한 GoogleService-Info.plist 파일을 Xcode 프로젝트에 추가한다. 이때 중요한 점은 파일이 프로젝트에만 보이는 것이 아니라, 실제로 앱 타깃(Target Membership)에 포함되어 있어야 한다는 점이다.
만약 이 파일이 번들에 포함되지 않으면 앱 실행 시 Firebase 설정이 정상적으로 동작하지 않을 수 있다.
3. Swift Package Manager로 Firebase SDK 설치하기
현재 Firebase는 Apple 플랫폼 프로젝트에서 Swift Package Manager 사용을 안내하고 있다. Xcode에서 패키지를 추가한 뒤, Crashlytics를 포함한 필요한 라이브러리를 선택하면 된다.
File > Add Package Dependencies
https://github.com/firebase/firebase-ios-sdk패키지 추가 시 보통 아래 모듈을 함께 선택한다.
- FirebaseAnalytics
- FirebaseCrashlytics
Analytics와 Crashlytics는 함께 사용하는 경우가 많다. Firebase 공식 iOS 설정 문서에서는 Apple 프로젝트에 Firebase SDK를 추가할 때 Swift Package Manager 사용을 안내하고 있다. :contentReference[oaicite:1]{index=1}
4. 앱 시작 시 Firebase 초기화하기
SDK를 추가했다면 앱 시작 시점에 Firebase를 초기화해야 한다. SwiftUI 앱과 UIKit 앱은 진입 지점이 조금 다르지만, 핵심은 앱 시작 과정에서 FirebaseApp.configure()를 호출하는 것이다.
SwiftUI 앱 예제
import SwiftUI
import FirebaseCore
@main
struct MyApp: App {
init() {
FirebaseApp.configure()
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}UIKit 앱 예제
import UIKit
import FirebaseCore
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
FirebaseApp.configure()
return true
}
}Firebase의 Apple 플랫폼 설정 문서에서는 앱 시작 시 Firebase를 구성하도록 안내하고 있다. :contentReference[oaicite:2]{index=2}
5. Crashlytics가 제대로 동작하는지 확인하기
Crashlytics는 설정만 해두고 끝내기보다, 실제 테스트 크래시를 한 번 발생시켜 정상 수집 여부를 확인하는 것이 좋다. Firebase 공식 가이드도 설정 후 테스트 크래시를 발생시켜서 연결 상태를 검증하는 흐름을 안내한다. :contentReference[oaicite:3]{index=3}
예를 들어 디버그 버튼이나 개발용 메뉴에서 아래와 같이 테스트 코드를 넣을 수 있다.
fatalError("Crashlytics test crash")앱이 실제로 종료된 뒤, 잠시 후 Firebase 콘솔에 해당 크래시가 보이면 기본 연결은 정상이다. 다만 릴리즈 빌드와 디버그 빌드에서 수집 결과가 다를 수 있으므로, 배포 전에 Archive 기준으로도 한 번 확인하는 것이 좋다.
6. dSYM 업로드를 위한 Run Script 설정 확인하기
Crashlytics 설정에서 많은 사람이 놓치는 부분이 바로 dSYM 업로드다. 앱 크래시를 보기만 하는 것은 가능할 수 있지만, dSYM이 누락되면 함수명과 코드 위치가 제대로 변환되지 않아 분석 효율이 크게 떨어진다.
Firebase Crashlytics iOS 시작 가이드에서는 빌드 시 dSYM 업로드를 위해 Crashlytics의 Run Script를 추가하도록 안내한다. :contentReference[oaicite:4]{index=4}
SPM 환경에서는 보통 다음과 비슷한 경로의 스크립트를 Build Phases의 Run Script에 넣는다. 프로젝트 구성과 Xcode 환경에 따라 실제 경로는 다를 수 있으니 현재 프로젝트 기준으로 확인하는 것이 좋다.
"${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"보통 확인할 항목은 다음과 같다.
- Build Phases에 Run Script가 추가되어 있는지
- Release / Archive 빌드에서도 실행되는지
- GoogleService-Info.plist가 올바른 타깃에 포함되어 있는지
- dSYM이 정상 생성되는지
7. 자주 발생하는 설정 실수
GoogleService-Info.plist가 타깃에 포함되지 않은 경우
파일을 프로젝트에 추가했더라도, 실제 앱 타깃에 체크되지 않으면 설정이 누락될 수 있다. 특히 Notification Service Extension이나 별도 타깃이 많은 프로젝트에서는 혼동하기 쉽다.
FirebaseApp.configure() 호출 누락
SDK를 설치했더라도 앱 시작 시 초기화 호출이 없으면 Crashlytics가 정상 동작하지 않는다. SwiftUI 프로젝트로 전환한 뒤 AppDelegate 기준 코드만 남겨두고 실제 호출이 빠지는 경우가 종종 있다.
Run Script가 Archive에서 실행되지 않는 경우
디버그 빌드에서는 문제가 없어 보이는데, 실제 릴리즈 빌드에서 dSYM 누락이 발생하는 경우가 있다. 이럴 때는 Build Phases와 Archive 결과를 같이 확인하는 것이 좋다.
8. 실제 운영에서 추천하는 점검 순서
Firebase Crashlytics를 적용한 뒤에는 아래 순서로 점검하면 비교적 빠르게 문제를 잡을 수 있다.
- Firebase 프로젝트와 iOS 앱 등록 확인
- GoogleService-Info.plist 추가 및 타깃 포함 여부 확인
- Swift Package Manager로 FirebaseCrashlytics 설치
- 앱 시작 시 FirebaseApp.configure() 호출
- 테스트 크래시 발생
- Firebase 콘솔에서 수집 확인
- Run Script 및 dSYM 업로드 상태 확인
9. Firebase Crashlytics 설정을 해두면 좋은 이유
Crashlytics는 앱 배포 이후 발생하는 문제를 더 빠르게 수집하고 정리하는 데 큰 도움이 된다. 특히 사용자가 직접 제보하지 않아도, 어떤 버전에서 어떤 유형의 크래시가 많이 발생하는지 추적할 수 있다.
운영 중인 iOS 앱에서는 단순한 로그 출력보다 이런 크래시 수집 도구가 훨씬 중요하다. 앱 규모가 커질수록 기기 종류, iOS 버전, 화면 흐름이 다양해지기 때문에, 문제가 발생했을 때 재현에만 의존하는 방식은 한계가 분명하다.
마무리
Firebase Crashlytics 설정 방법을 정리하면 다음과 같다.
- Firebase 프로젝트에 iOS 앱을 등록한다.
- GoogleService-Info.plist 파일을 프로젝트에 추가한다.
- Swift Package Manager로 FirebaseCrashlytics를 설치한다.
- 앱 시작 시 FirebaseApp.configure()를 호출한다.
- 테스트 크래시로 연결 상태를 확인한다.
- Run Script와 dSYM 업로드 설정까지 점검한다.
처음 설정할 때는 단계가 많아 보이지만, 한 번 정확하게 정리해두면 이후 크래시 분석 효율이 크게 좋아진다. 특히 실제 서비스 앱을 운영 중이라면 Crashlytics는 거의 필수에 가깝다고 느껴질 만큼 유용하다.
같이 보면 좋은 글
- Firebase Crashlytics dSYM Missing 오류 해결 방법
- iOS dSYM 파일 위치 확인 방법
- Xcode Archive와 Release 빌드 차이 정리
- Swift UIButton 이미지와 텍스트 간격 설정 방법
Firebase Crashlytics 관련 글
'IT' 카테고리의 다른 글
| SwiftUI NavigationStack 사용 방법 정리 (iOS 16+) (0) | 2026.03.14 |
|---|---|
| Firebase Crashlytics SPM 설치 방법 (Swift / iOS) (1) | 2026.03.14 |
| Firebase Crashlytics에서 UUID Missing 해결 방법 (iOS / Swift) (0) | 2026.03.14 |
| Firebase Crashlytics 크래시 로그 확인하는 방법 (Swift / iOS) (0) | 2026.03.14 |
| Firebase Crashlytics dSYM Missing 오류 해결 방법 (SPM 환경 포함) (0) | 2026.03.14 |