Android NDK 비정상 종료 보고서 받기

Android 앱에 네이티브 라이브러리가 포함되어 있는 경우 Firebase Crashlytics에서 앱의 빌드 구성을 소규모 업데이트하여 네이티브 코드에 대한 전체 스택 트레이스와 상세한 비정상 종료 보고서를 사용할 수 있습니다.

이 가이드에서는 NDK용 Firebase Crashlytics SDK를 사용하여 비정상 종료 보고를 구성하는 방법을 설명합니다.

Unity 프로젝트에서 Crashlytics를 시작하는 방법을 알아보려면 Unity 시작 가이드를 참조하세요.

시작하기 전에

아직 추가하지 않았다면 Android 프로젝트에 Firebase를 추가합니다. Android 앱이 없다면 샘플 앱을 다운로드하면 됩니다.
권장: 비정상 종료가 발생하지 않은 사용자, 탐색경로 로그, 신속 알림과 같은 기능을 사용하려면 Firebase 프로젝트에서 Google 애널리틱스를 사용 설정해야 합니다.
- 기존 Firebase 프로젝트에 Google 애널리틱스를 사용 설정하지 않은 경우 Firebase Console의 > 프로젝트 설정의 통합 탭에서 Google 애널리틱스를 사용 설정할 수 있습니다.
- 새 Firebase 프로젝트를 만드는 경우 프로젝트 생성 워크플로 중에 Google 애널리틱스를 사용 설정합니다.

1단계: 앱에 NDK용 Crashlytics SDK 추가

모듈(앱 수준) Gradle 파일(일반적으로 <project>/<app-module>/build.gradle)에서 Crashlytics NDK Android 라이브러리의 종속 항목을 추가합니다. 라이브러리 버전 관리 제어에는 Firebase Android BoM을 사용하는 것이 좋습니다.

Crashlytics 사용 환경을 최적화하려면 Firebase 프로젝트에서 Google 애널리틱스를 사용 설정하고 Google 애널리틱스용 Firebase SDK를 앱에 추가하는 것이 좋습니다.

Java

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.4.1')

    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk'
    implementation 'com.google.firebase:firebase-analytics'
}

Firebase Android BoM을 사용하면 앱에서 항상 호환되는 Firebase Android 라이브러리 버전만 사용합니다.

(대안) BoM을 사용하지 않고 Firebase 라이브러리 종속 항목을 추가합니다.

Firebase BoM을 사용하지 않도록 선택한 경우에는 종속 항목 줄에 각 Firebase 라이브러리 버전을 지정해야 합니다.

앱에서 여러 Firebase 라이브러리를 사용하는 경우 모든 버전이 호환되도록 BoM을 사용하여 라이브러리 버전을 관리하는 것이 좋습니다.

dependencies {
    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk:18.2.13'
    implementation 'com.google.firebase:firebase-analytics:21.1.1'
}

Kotlin+KTX

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:30.4.1')

    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk'
    implementation 'com.google.firebase:firebase-analytics-ktx'
}

Firebase Android BoM을 사용하면 앱에서 항상 호환되는 Firebase Android 라이브러리 버전만 사용합니다.

(대안) BoM을 사용하지 않고 Firebase 라이브러리 종속 항목을 추가합니다.

Firebase BoM을 사용하지 않도록 선택한 경우에는 종속 항목 줄에 각 Firebase 라이브러리 버전을 지정해야 합니다.

앱에서 여러 Firebase 라이브러리를 사용하는 경우 모든 버전이 호환되도록 BoM을 사용하여 라이브러리 버전을 관리하는 것이 좋습니다.

dependencies {
    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-crashlytics-ndk:18.2.13'
    implementation 'com.google.firebase:firebase-analytics-ktx:21.1.1'
}

2단계: 앱에 Crashlytics Gradle 플러그인 추가

루트 수준(프로젝트 수준) Gradle 파일(<project>/build.gradle)에서 Crashlytics Gradle 플러그인을 buildscript 종속 항목으로 추가합니다.

buildscript {
    repositories {
      // Make sure that you have the following two repositories
      google()  // Google's Maven repository
      mavenCentral()  // Maven Central repository
    }

    dependencies {
        ...
        classpath 'com.android.tools.build:gradle:7.2.0'

        // Make sure that you have the Google services Gradle plugin dependency
        classpath 'com.google.gms:google-services:4.3.14'

        // Add the dependency for the Crashlytics Gradle plugin
        classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.2'
    }
}

모듈(앱 수준) Gradle 파일(일반적으로 <project>/<app-module>/build.gradle)에서 Crashlytics Gradle 플러그인을 추가합니다.

plugins {
    id 'com.android.application'

    // Make sure that you have the Google services Gradle plugin
    id 'com.google.gms.google-services'

    // Add the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics'
    ...
}

3단계: 빌드에 `firebaseCrashlytics` 확장 프로그램 추가

모듈(앱 수준) Gradle 파일(일반적으로 app/build.gradle)에서 firebaseCrashlytics 확장 프로그램을 추가합니다.

Java

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

Kotlin+KTX

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

4단계: 네이티브 기호 자동 업로드 설정

NDK 비정상 종료로부터 읽기 가능한 스택 트레이스를 생성하려면 Crashlytics에서 네이티브 바이너리의 기호에 대해 파악해야 합니다. Crashlytics Gradle 플러그인에는 이 과정을 자동화하는 uploadCrashlyticsSymbolFileBUILD_VARIANT 태스크가 포함되어 있습니다.

자동화된 기호 업로드를 위한 태스크에 액세스할 수 있도록 모듈(앱 수준) Gradle 파일에서 nativeSymbolUploadEnabled가 true로 설정되어 있는지 확인합니다.
스택 트레이스에 나타나는 메서드 이름의 경우 NDK 라이브러리를 빌드할 때마다 uploadCrashlyticsSymbolFileBUILD_VARIANT 태스크를 명시적으로 호출해야 합니다. 예를 들면 다음과 같습니다.
```
>./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT
```
NDK용 Crashlytics SDK와 Crashlytics Gradle 플러그인은 모두 네이티브 공유 객체 내에 GNU 빌드 ID가 있어야 합니다.

각 바이너리에서 readelf -n을 실행하여 이 ID가 있는지 확인할 수 있습니다. 빌드 ID가 없는 경우 빌드 시스템의 플래그에 -Wl,--build-id를 추가하여 문제를 해결하세요.

5단계: 테스트 비정상 종료를 강제로 적용하여 설정 완료

Crashlytics 설정을 완료하고 Firebase Console의 Crashlytics 대시보드에 초기 데이터를 표시하려면 테스트 비정상 종료를 강제로 적용해야 합니다.

테스트 비정상 종료를 강제로 적용하는 데 사용할 수 있는 코드를 앱에 추가합니다.

앱의 MainActivity에서 다음 코드를 사용하여, 누르면 비정상 종료를 일으키는 버튼을 앱에 추가할 수 있습니다. 버튼에 'Test Crash'라는 라벨이 지정되어 있습니다.

Java

Button crashButton = new Button(this);
crashButton.setText("Test Crash");
crashButton.setOnClickListener(new View.OnClickListener() {
   public void onClick(View view) {
       throw new RuntimeException("Test Crash"); // Force a crash
   }
});

addContentView(crashButton, new ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT));

Kotlin+KTX

val crashButton = Button(this)
crashButton.text = "Test Crash"
crashButton.setOnClickListener {
   throw RuntimeException("Test Crash") // Force a crash
}

addContentView(crashButton, ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT))

앱을 빌드하고 실행합니다.
앱의 첫 번째 비정상 종료 보고서를 전송하려면 테스트 비정상 종료를 강제로 적용합니다.
1. 테스트 기기 또는 에뮬레이터에서 앱을 엽니다.
2. 앱에서 위 코드를 사용하여 추가한 'Test Crash' 버튼을 누릅니다.
3. 앱이 비정상 종료된 후에는 앱을 다시 시작하여 비정상 종료 보고서를 Firebase에 전송할 수 있도록 합니다.
Firebase Console의 Crashlytics 대시보드로 이동하여 테스트 비정상 종료를 확인합니다.

Console을 새로고침하고 5분 후에도 테스트 비정상 종료가 표시되지 않으면 디버그 로깅을 사용 설정하여 앱에서 비정상 종료 보고서를 전송하는지 확인합니다.

모든 작업이 완료되었습니다. 이제 Crashlytics에서 앱의 비정상 종료를 모니터링합니다. Crashlytics 대시보드에서 비정상 종료 보고서와 통계를 확인하고 조사할 수 있습니다.

기호 업로드를 위한 대체 옵션

이 페이지 상단의 기본 워크플로는 표준 Gradle 빌드에 적용할 수 있습니다. 그러나 일부 앱은 다른 구성 또는 도구(예: Gradle 이외의 빌드 프로세스)를 사용합니다. 이러한 상황에서는 다음 옵션을 사용하면 기호를 성공적으로 업로드하는 데 도움이 될 수 있습니다.

옵션: 라이브러리 모듈 및 외부 종속 항목 기호 업로드

이 옵션은 다음과 같은 상황에서 도움이 될 수 있습니다.

Gradle 내에서 맞춤설정된 NDK 빌드 프로세스를 사용하는 경우
네이티브 라이브러리가 라이브러리/기능 모듈에서 빌드되었거나 타사에서 제공되는 경우
자동 기호 업로드 태스크가 실패하거나 대시보드에 기호화되지 않은 비정상 종료가 표시되는 경우

이 옵션에 대한 안내 보기

표준 Crashlytics 기호 업로드 태스크에서는 CMake와 같은 표준 NDK 빌드 도구를 사용하여 앱 모듈 Gradle 빌드의 일부로 네이티브 라이브러리를 빌드한다고 가정합니다.

그러나 Gradle 내에서 맞춤설정된 NDK 빌드 프로세스를 사용하거나 네이티브 라이브러리가 라이브러리/기능 모듈에서 빌드되었거나 타사에서 제공되는 경우 삭제되지 않은 라이브러리의 경로를 명시적으로 지정해야 할 수 있습니다. 이를 위해 build.gradle 파일의 firebaseCrashlytics 확장 프로그램 내에 unstrippedNativeLibsDir 속성을 추가할 수 있습니다.

이 페이지 앞부분의 기본 워크플로에서 다음 초기 태스크를 완료했는지 확인합니다.
자동 기호 업로드 태스크가 기호 정보를 찾을 수 있도록 모듈(앱 수준) build.gradle 파일에 다음을 추가합니다.
```
// ...

android {
    // ...
    buildTypes {
        release {
            firebaseCrashlytics {
                nativeSymbolUploadEnabled true
                unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY")
            }
        }
    }
}
```
Crashlytics 플러그인은 지정된 디렉터리에서 .so 확장자를 포함하는 네이티브 라이브러리를 재귀적으로 검색합니다. 그러면 Crashlytics가 이러한 모든 라이브러리에서 디버깅 기호를 추출하여 Firebase 서버에 업로드합니다.

unstrippedNativeLibsDir 속성에서 지정할 수 있는 사항은 다음과 같습니다.
- java.lang.String, java.io.File 또는 org.gradle.api.file.FileCollection 등 org.gradle.api.Project#files(Object...)에 허용되는 인수
- 단일 빌드 버전에 대한 여러 디렉터리 - 목록이나 FileCollection 인스턴스를 제공하여 지정
마지막으로 테스트 비정상 종료를 강제로 적용하여 Crashlytics 설정을 완료하고 Firebase Console의 Crashlytics 대시보드에서 초기 데이터를 확인합니다.

옵션: Gradle 이외의 빌드 또는 액세스할 수 없는 삭제되지 않은 네이티브 라이브러리의 기호 업로드

이 옵션은 다음과 같은 상황에서 도움이 될 수 있습니다.

Gradle 이외의 빌드 프로세스를 사용하는 경우
삭제되지 않은 네이티브 라이브러리가 Gradle 빌드 중에 액세스할 수 없는 방식으로 제공된 경우

이 옵션에 대한 안내 보기

이 옵션을 사용하려면 출시 빌드를 만들거나 Firebase Console에서 기호화된 스택 트레이스를 보려는 빌드를 만들 때 Firebase CLI 명령어를 실행해야 합니다.

이 페이지 앞부분의 기본 워크플로에서 다음 초기 태스크를 완료했는지 확인합니다.
1. Firebase Console에서 Crashlytics를 사용 설정했습니다.
2. NDK용 Crashlytics SDK 및 Crashlytics Gradle 플러그인을 추가했습니다.
이 옵션을 사용하면 firebaseCrashlytics 확장 프로그램을 추가하거나 자동 기호 업로드를 설정할 필요가 없습니다. 대신 Firebase CLI(아래의 다음 단계)를 사용하여 기호 파일을 생성하고 업로드하기 때문입니다.
기호 업로드를 위한 환경 및 프로젝트를 설정합니다.
1. 안내에 따라 Firebase CLI를 설치합니다.
  
  CLI를 이미 설치했다면 최신 버전으로 업데이트해야 합니다.
2. (Android API 수준 30 이상을 사용하는 앱만 해당) 앱의 AndroidManifest.xml 템플릿을 업데이트하여 포인터 태그를 사용 중지합니다.
  1. Android 플레이어 설정(Android Player Settings) > 게시 설정(Publishing Settings) > 빌드(Build) > 커스텀 기본 매니페스트(Custom Main Manifest) 체크박스를 선택합니다.
  2. Assets/Plugins/Android/AndroidManifest.xml에 있는 매니페스트 템플릿을 엽니다.
  3. <application android:allowNativeHeapPointerTagging="false" ... /> 속성을 애플리케이션 태그에 추가합니다.
프로젝트를 빌드합니다.

기호 정보를 업로드합니다.

빌드가 완료되면 Crashlytics 호환 기호 파일을 생성하고 다음 Firebase CLI 명령어를 실행하여 Firebase 서버에 업로드합니다.

firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS

FIREBASE_APP_ID: 패키지 이름이 아닌 Firebase Android 앱 ID
Firebase Android 앱 ID 예시: 1:567383003300:android:17104a2ced0c9b9b
Firebase 앱 ID를 찾아야 하나요?
Firebase 앱 ID를 찾는 방법에는 두 가지가 있습니다.
- google-services.json 파일에서 mobilesdk_app_id 값이 앱 ID입니다.
- Firebase Console에서 프로젝트 설정으로 이동합니다. 내 앱 카드까지 아래로 스크롤한 다음 원하는 Firebase 앱을 클릭하여 앱 ID를 찾습니다.
PATH/TO/SYMBOLS: CLI에서 생성된 기호 파일 경로
- Android 스튜디오 프로젝트로 내보내졌습니다. PATH/TO/SYMBOLS는 모든 디렉터리가 될 수 있습니다. Firebase CLI는 지정된 디렉터리에서 .so 확장자를 포함하는 네이티브 라이브러리를 재귀적으로 검색합니다.
- Unity 내에서 직접 APK를 빌드했습니다. PATH/TO/SYMBOLS는 빌드가 완료될 때 프로젝트 루트 디렉터리에서 생성된 압축된 기호 파일의 경로입니다(예: myproject/myapp-1.0-v100.symbols.zip).

기호 파일 생성 및 업로드에 Firebase CLI 명령어를 사용하기 위한 고급 옵션 보기

플래그	설명
`--generator=csym`	기본 Breakpad 생성기 대신 기존 cSYM 기호 파일 생성기를 사용합니다. 사용하지 않는 것이 좋습니다. 기본 Breakpad 기호 파일 생성기를 사용하는 것이 좋습니다.
`--generator=breakpad`	Breakpad 기호 파일 생성기를 사용합니다. 기호 파일 생성의 기본값은 Breakpad입니다. 빌드 구성에 `symbolGenerator { csym() }`를 추가했고 대신 Breakpad를 사용하도록 재정의하려는 경우에만 이 플래그를 사용합니다.
`--dry-run`	기호 파일을 생성하지만 업로드하지 않습니다. 이 플래그는 전송된 파일의 콘텐츠를 검사하려는 경우에 유용합니다.
`--debug`	디버깅 정보를 추가로 제공합니다.

마지막으로 테스트 비정상 종료를 강제로 적용하여 Crashlytics 설정을 완료하고 Firebase Console의 Crashlytics 대시보드에서 초기 데이터를 확인합니다.

비정상 종료를 강제로 적용하는 과정에서 앱을 빌드한 후에는 Firebase CLI crashlytics:symbols:upload 명령어를 실행하여 기호 파일을 업로드해야 합니다.

문제 해결

Firebase Console과 logcat에 서로 다른 스택 트레이스가 보이는 경우 문제 해결 가이드를 참조하세요.

다음 단계

보고 선택 옵션, 로그, 키를 추가하고 심각하지 않은 오류를 추적하여 비정상 종료 보고서 설정을 맞춤설정하세요.
Google Play와 통합하여 Crashlytics 대시보드에서 직접 Android 앱의 비정상 종료 보고서를 Google Play 트랙별로 필터링할 수 있도록 합니다. 이렇게 하면 특정 빌드에 대시보드를 더 집중할 수 있습니다.

Android NDK 비정상 종료 보고서 받기

시작하기 전에

1단계: 앱에 NDK용 Crashlytics SDK 추가

Java

Kotlin+KTX

2단계: 앱에 Crashlytics Gradle 플러그인 추가

3단계: 빌드에 firebaseCrashlytics 확장 프로그램 추가

Java

Kotlin+KTX

4단계: 네이티브 기호 자동 업로드 설정

5단계: 테스트 비정상 종료를 강제로 적용하여 설정 완료

Java

Kotlin+KTX

기호 업로드를 위한 대체 옵션

옵션: 라이브러리 모듈 및 외부 종속 항목 기호 업로드

옵션: Gradle 이외의 빌드 또는 액세스할 수 없는 삭제되지 않은 네이티브 라이브러리의 기호 업로드

문제 해결

다음 단계

3단계: 빌드에 `firebaseCrashlytics` 확장 프로그램 추가