Google I/O 2023에서 Firebase의 주요 소식을 확인하세요. 자세히 알아보기

게임 빌드, 설치, 실행 프로세스 디버깅

소개

다음은 Unity용 Firebase SDK를 사용하여 Unity 게임의 컴파일 및 빌드 프로세스를 디버깅하는 방법에 대한 가이드입니다. 여기에서는 업데이트 후에 또는 새 플랫폼에 게임을 구성하고 빌드하는 도중에 발생할 수 있는 보다 일반적인 문제를 조사하고 해결하는 방법을 설명합니다. 프로세스에서 이러한 오류가 발생할 수 있는 순서대로 안내하고 있으니 순서대로 참고하여 하나씩 문제를 해결하면서 진행하시기 바랍니다.

이 문서 외에도 Unity용 Firebase FAQ를 통해 자세한 내용을 참조하세요.

재생 모드 컴파일 문제

첫 번째 클래스의 빌드 문제는 모바일 빌드를 시작하기 전에 편집기에서 테스트하는 동안 발생할 수 있습니다. 이 섹션에서는 재생 모드 이전에 또한 재생 도중에 발생하는 모든 Firebase 오류에 관해 다룹니다.

Unity가 종속 항목, 코드 또는 기타 애셋 변경을 시작하거나 변경사항을 감지하면 프로젝트를 다시 빌드하려고 시도합니다. 이때 프로젝트를 컴파일할 수 없는 경우 편집기가 콘솔에 컴파일 오류를 로깅하고, 재생 모드로 전환하려고 하면 Unity의 Scene(장면) 탭에 All compiler errors have to be fixed before you can enter playmode!라는 오류 팝업이 표시됩니다.

Firebase 관련 컴파일 문제 디버깅

유형, 클래스, 메서드, 구성원 누락

많은 Firebase 관련 문제는 편집기와 컴파일러가 필요한 유형, 클래스, 메서드, 구성원을 찾지 못하기 때문에 발생합니다. 이러한 문제의 일반적인 증상은 다음과 같습니다.

The type or namespace name ‘<CLASS OR NAMESPACE NAME>' could not be found. Are you missing a using directive or an assembly reference?

The type or namespace name <TYPE OR NAMESPACE NAME> does not exist in the namespace ‘Firebase<.OPTIONAL NESTED NAMESPACE NAME PATH>' (are you missing an assembly reference?)

‘<CLASS NAME>' does not contain a definition for ‘<MEMBER VARIABLE OR METHOD NAME>'

해결 단계:

코드에 Firebase 클래스 또는 메서드를 사용하는 경우, 요구되는 특정 Firebase 제품에 올바른 using 지시어를 사용하여 제공하고 있는지 확인합니다.
1. MechaHamster: Level Up With Firebase 버전의 예시:
  1. using Firebase.RemoteConfig;
  2. using Firebase.Crashlytics;
적절한 Firebase 패키지를 가져왔는지 확인합니다.
1. 적절한 패키지를 가져오려면 다음 중 하나를 수행합니다.
  1. Firebase Unity SDK를 .unitypackage로 추가합니다.
  2. 또는 추가 Unity 설치 옵션의 대안 중 하나를 살펴보고 수행합니다.
2. 프로젝트 및 EDM4U의 모든 Firebase 제품은 다음 조건을 충족해야 합니다.
  - 동일한 버전입니다.
  - .unitypackage 또는 Unity Package Manager를 통해서만 설치되었습니다.
'10.0.0' 버전 이전에 Firebase Unity SDK를 .unitypackage로 가져온 경우 Firebase Unity SDK ZIP 파일에 .NET 3.x 및 .NET 4.x 지원 패키지가 모두 포함되어 있습니다. 프로젝트에 호환되는 .NET Framework 수준만 포함되어 있는지 확인합니다.
1. Unity 편집기 버전과 .NET Framework 수준 간의 호환성은 Unity 프로젝트에 Firebase 추가를 참조하세요.
2. 실수로 잘못된 .NET Framework 수준에서 Firebase 패키지를 가져왔거나 .unitypackage를 사용하는 대신 추가 Unity 설치 옵션 중 하나로 전환해야 하는 경우 이 마이그레이션 섹션에 설명된 메서드를 통해 모든 Firebase 패키지를 삭제한 다음 이를 다시 가져오는 것이 가장 깔끔한 방법입니다.
편집기에서 프로젝트를 다시 빌드하고 있는지, 재생 시도가 프로젝트의 최신 상태를 반영하는지 확인합니다.
1. 기본적으로 Unity 편집기는 애셋 또는 구성 변경사항이 감지될 때마다 다시 빌드하도록 설정되어 있습니다.
2. 이 기능이 사용 중지되었으며 Unity 편집기가 수동 새로고침/다시 컴파일로 설정되었을 수 있습니다. 조사해 보고 이러한 경우에 해당한다면 수동으로 새로고침해 보세요.

재생 모드 런타임 오류

게임이 시작되기는 하지만 실행 중에 Firebase 관련 문제가 발생하는 경우 다음을 시도해 보세요.

Mac OS의 '보안 및 개인 정보 보호'에서 Firebase 번들 승인 확인

Mac OS의 편집기에서 게임을 시작할 때 '개발자를 확인할 수 없으므로 FirebaseCppApp-<version>.bundle을 열 수 없습니다.'라는 대화상자가 나타나면 해당 번들 파일을 Mac의 보안 및 개인 정보 보호 메뉴에서 승인해야 합니다.

이렇게 하려면 Apple 아이콘 > System Preferences(시스템 환경설정) > Security & Privacy(보안 및 개인 정보 보호)를 클릭합니다.

페이지의 절반 정도까지 내려오면 보안 메뉴에 '확인된 개발자가 제공하지 않으므로 'FirebaseCppApp-<version>.bundle' 사용이 차단되었습니다.'라는 섹션이 있습니다.

Allow Anyway(무시하고 허용) 버튼을 클릭합니다.

Unity로 돌아가서 다시 Play(재생)를 누릅니다.

그러면 다음과 같이 첫 번째 경고와 유사한 경고가 표시됩니다.

Open(열기)을 누르면 프로그램을 진행할 수 있습니다. 이 특정 파일에 관한 메시지는 다시 표시되지 않습니다.

프로젝트에 유효한 구성 파일이 포함되어 있고 사용 중인지 확인

File(파일) > Build Settings(빌드 설정)에서 빌드 설정이 원하는 대상(iOS 또는 Android)으로 설정되어 있는지 확인합니다. 자세한 내용은 Unity 빌드 설정 문서를 참조하세요.
앱의 구성 파일(Android의 경우 google-services.json, iOS의 경우 GoogleService-Info.plist)을 다운로드하고 Project Settings(프로젝트 설정) > Your Apps(내 앱)의 Firebase Console에서 대상을 빌드합니다. 이 파일이 이미 있다면 프로젝트에서 삭제하고 최신 버전으로 바꿉니다. 이때 파일 이름에 '(1)' 또는 다른 숫자가 붙지 않고 위에 표시된 대로 철자가 정확하게 입력되었는지 확인합니다.
Assets/StreamingAssets/의 파일과 관련된 메시지가 콘솔에 포함된 경우 Unity에서 파일을 수정할 수 없다는 콘솔 메시지가 없어야 합니다.
Assets/StreamingAssets/google-services-desktop.json이 생성되고 다운로드한 구성 파일과 일치하는지 확인합니다.
- 자동으로 생성되지 않고 StreamingAssets/도 존재하지 않으면 Assets 디렉터리에 수동으로 디렉터리를 만듭니다.
- 이제 Unity에서 google-services-desktop.json을 생성했는지 확인합니다.

모든 Firebase 제품 및 EDM4U가 `.unitypackage` 또는 Unity Package Manager를 통해서만 설치되었는지 확인

Assets/ 폴더와 Unity Package Manager를 모두 확인하여 Firebase SDK와 EDM4U가 둘 중 한 가지 메서드를 통해서만 설치되었는지 확인합니다.
Google에서 개발한 플러그인(예: Google Play) 및 서드 파티 플러그인 일부가 EDM4U를 사용해야 할 수 있습니다. 이러한 플러그인은 .unitypackage 또는 Unity Package Manager(UPM) 패키지에 EDM4U를 포함하고 있을 수 있습니다. 프로젝트에 EDM4U 사본이 하나만 있음을 확인합니다. EDM4U를 사용하는 UPM 패키지가 있는 경우 Unity 보관용 Google API 페이지에서 찾을 수 있는 EDM4U의 UPM 버전만 유지하는 것이 가장 좋습니다.

프로젝트의 모든 Firebase 제품이 동일한 버전인지 확인

.unitypackage를 통해 Firebase SDK를 설치한 경우 Assets/Firebase/Plugins/x86_64/ 아래의 모든 FirebaseCppApp 라이브러리가 동일한 버전인지 확인합니다.
Unity Package Manager(UPM)를 통해 Firebase SDK를 설치한 경우 Windows > Package Manager(패키지 관리자)를 열고 'Firebase'를 검색하여 모든 Firebase 패키지가 동일한 버전인지 확인합니다.
프로젝트에 다른 버전의 Firebase SDK가 포함되어 있는 경우 모든 Firebase SDK를 완전히 삭제한 후 동일한 버전으로 다시 설치하는 것이 좋습니다. 가장 깔끔한 방법은 이 마이그레이션 섹션에 언급된 메서드를 통해 모든 Firebase 패키지를 삭제하는 것입니다.

리졸버 및 대상 기기 빌드 오류

게임이 편집기에서 작동하는 경우(선택한 적절한 빌드 대상에 맞게 구성됨) 이제 External Dependency Manager for Unity(EDM4U)가 올바르게 구성되어 작동하는지 확인합니다.

프로세스의 이 부분에 대한 단계별 안내가 EDM4U GitHub 저장소에 포함되어 있으니 먼저 검토하고 이에 따라 계속 진행하세요.

'단일 Dex' 문제 및 축소(Cloud Firestore를 사용하는 경우 필수)

Android 앱을 빌드하는 동안 단일 dex 파일 보유와 관련해 빌드 실패가 발생할 수 있습니다. 프로젝트가 Gradle 빌드 시스템을 사용하도록 구성된 경우 오류 메시지는 다음과 유사합니다.

Cannot fit requested classes in a single dex file.

.dex 파일은 Android 애플리케이션의 클래스 정의 및 관련 부속 데이터를 저장하는 데 사용됩니다. 단일 dex 파일은 참조할 수 있는 메서드 수가 65,536개로 제한됩니다. 프로젝트에서 모든 Android 라이브러리의 총 메서드 수가 이 한도를 초과하면 빌드에 실패하게 됩니다.

다음 두 단계를 순차적으로 적용할 수 있습니다. 축소로 문제를 해결할 수 없는 경우에 한해 멀티덱스를 사용 설정합니다.

축소 사용 설정

Unity는 2017.2 버전에 Minification(축소) 기능을 도입했습니다. 이는 사용하지 않는 코드를 제거하는 기능으로 단일 dex 파일에서 참조된 메서드의 총 개수를 줄일 수 있습니다. * 이 옵션은 Player Settings(플레이어 설정) > Android > Publishing Settings(게시 설정) > Minify(축소)에 있습니다. * 옵션은 Unity 버전마다 다를 수 있으므로 공식 Unity 문서를 참조하세요.

멀티덱스 사용 설정

축소를 사용 설정한 후에도 참조된 메서드의 개수가 여전히 한도를 초과하는 경우 또 다른 방법은 multidex를 사용 설정하는 것입니다. Unity에서 이를 수행하는 방법에는 여러 가지가 있습니다.

Player Settings(플레이어 설정)의 Custom Gradle Template(커스텀 Gradle 템플릿)이 사용 설정된 경우 mainTemplate.gradle을 수정합니다.
내보낸 프로젝트를 빌드하기 위해 Android 스튜디오를 사용하는 경우 모듈 수준 build.gradle 파일을 수정합니다.

자세한 내용은 멀티덱스 사용자 가이드를 참조하세요.

대상 기기 런타임 오류 이해 및 수정

게임이 편집기에서 작동하고 대상 기기에 빌드 및 설치도 되는데 런타임 오류가 발생하는 경우 기기에서 생성된 로그를 검사하고 조사합니다.

이 섹션에서는 로그에서 발생할 수 있는 오류를 조사하는 방법과 기기 또는 시뮬레이터에서 런타임에만 발생하는 오류에 대해 자세히 설명합니다.

Android

시뮬레이터

에뮬레이터의 콘솔에 표시된 로그를 검사하거나 Logcat 창을 확인합니다.

기기

adb 및 adb logcat과 그 사용 방법을 숙지합니다.

명령줄 환경의 다양한 도구를 사용하여 출력을 필터링할 수도 있지만 대신 logcat의 옵션을 확인하는 것이 좋습니다.
깔끔한 슬레이트에서 ADB 세션을 시작하는 간단한 방법은 다음과 같습니다.
```
adb logcat -c && adb logcat <OPTIONS>
```
여기서 OPTIONS는 출력을 필터링하기 위해 명령줄에 전달하는 플래그입니다.

Android 스튜디오를 통해 Logcat 사용

Android 스튜디오를 통해 Logcat을 사용하면 생산적인 검색을 보다 간단하게 할 수 있는 추가 검색 도구가 제공됩니다.

iOS

로그 검사

실제 기기를 실행 중인 경우 이를 컴퓨터에 연결합니다. Xcode에서 lldb를 검사합니다.

Swift 문제

swift를 언급하는 오류 로그가 발생하면 관련 External Dependency Manager for Unity 섹션을 참조하세요.

추가 단계

게임에 Firebase와 관련된 컴파일, 빌드 또는 실행 문제가 계속 발생하는 경우 Unity용 Firebase SDK 문제 페이지를 살펴보고 새 문제를 제출해 보세요. 또한 추가 옵션에 관한 정보는 Firebase 지원 페이지를 참조하세요.