새로운 Firebase Studio 기능부터 AI 통합 방법까지 I/O에서 발표된 모든 내용을 확인해 보세요. 블로그 읽기

Unity와 Firebase의 문제 해결 및 FAQ

이 페이지에서는 Firebase 사용 시 발생할 수 있는 Unity 관련 문제의 팁과 문제 해결 방법을 제공합니다.

아래에서 찾을 수 없는 다른 문제나 어려운 점이 있으신가요? Firebase 전체 FAQ 또는 제품별 FAQ를 살펴보려면 기본 Firebase FAQ를 확인하세요.

Unity 2017.x 이상 버전을 사용하는 경우 .NET 호환성

Firebase는 Unity 2017 이상 버전에서 실험용 빌드 옵션으로 .NET 4.x를 지원합니다. 이전 버전의 .NET에서는 Firebase 플러그인이 Parse SDK 구성요소를 사용해 일부 .NET 4.x 클래스를 제공합니다.

따라서 Firebase Unity SDK 버전 5.4.0 이상은 Firebase Unity SDK의 dotnet3 및 dotnet4 디렉터리에서 .NET 3.x 또는 .NET 4.x와 호환되는 플러그인을 제공합니다.

프로젝트에서 사용 설정된 .NET 버전과 호환되지 않는 Firebase 플러그인을 가져오면 Parse SDK로 구현된 .NET 프레임워크의 일부 유형에서 컴파일 오류가 발생할 수 있습니다.

.NET 3.x를 사용하는 경우 다음과 같은 방법으로 컴파일 오류를 해결하세요.

모든 플랫폼에서 다음 DLL을 삭제하거나 사용 중지합니다.
- Parse/Plugins/dotNet45/Unity.Compat.dll
- Parse/Plugins/dotNet45/Unity.Tasks.dll
모든 플랫폼에서 다음 DLL을 사용 설정합니다.
- Parse/Plugins/Unity.Compat.dll
- Parse/Plugins/Unity.Tasks.dll

.NET 4.x를 사용하는 경우 다음과 같은 방법으로 컴파일 오류를 해결하세요.

모든 플랫폼에서 다음 DLL을 삭제하거나 사용 중지합니다.
- Parse/Plugins/Unity.Compat.dll
- Parse/Plugins/Unity.Tasks.dll
모든 플랫폼에서 다음 DLL을 사용 설정합니다.
- Parse/Plugins/dotNet45/Unity.Compat.dll
- Parse/Plugins/dotNet45/Unity.Tasks.dll

다른 Firebase 플러그인을 가져오는 경우

Unity 프로젝트에서 Assets(애셋) > Play Services Resolver(Play 서비스 리졸버) > Version Handler(버전 핸들러) > Update(업데이트)로 이동하여 프로젝트에 해당하는 올바른 DLL을 사용 설정합니다.

.NET 4.x 프로젝트에서 Unity 2017.1 IL2CPP 컴파일

따라서 Firebase Unity SDK 버전 5.4.0 이상은 파싱 유형(예: System.Threading.Tasks.Task의 파싱 구현)을 .NET 프레임워크에 전달하는 유형 전달 DLL을 제공합니다. 하지만 Unity 2017.1.x에 제공된 IL2CPP(C#을 C++로 변환하는 트랜스파일러)는 유형 전달 DLL을 올바르게 처리하지 않기 때문에 다음과 비슷한 빌드 오류가 발생합니다.

Fatal error in Unity CIL Linker Mono.Cecil.ResolutionException: Failed to
resolve System.Threading.Tasks.TaskCompletionSource`1<T>

현재 Unity 2017.1에서 발생하는 .NET 4.x IL2CPP 빌드 오류 해결 방법은 없으므로 IL2CPP로 컴파일한 프로젝트에서 .NET 4.x를 사용하려면 Unity 2017.2 이상으로 업그레이드해야 합니다.

Unity 2017.2 네트워킹

Firebase Realtime Database는 .NET 네트워킹 스택을 사용해 TLS 네트워크 연결을 만듭니다. Unity 2017.2에서는 .NET 4.6 사용 시 TLS 기능에 문제가 생겨 편집기 및 데스크톱의 Realtime Database 플러그인에 오류가 발생합니다.

이 문제는 해결 방법이 없으며 2017.1 또는 2017.3 등 다른 버전의 Unity를 사용해야 합니다.

Unity 2020에서 Firebase Android 구성 파일 누락

Gradle 빌드를 맞춤설정할 수 없는 Unity 버전을 지원하기 위해 Firebase 편집기 도구에서는 Android 빌드로 패키징할 Android 리소스로 Assets/Plugins/Android/Firebase/res/values/google-services.xml을 생성합니다. Firebase SDK는 이 리소스를 사용하여 기본 FirebaseApp 인스턴스를 초기화할 수 있습니다.

Unity 2020에서 모든 Android 리소스는 .androidlib 서픽스가 있는 디렉터리에 있어야 합니다. 프로젝트가 Assets/Plugins/Android/Firebase 디렉터리를 생성하는 Firebase SDK를 사용하는 경우 이름을 Assets/Plugins/Android/Firebase.androidlib로 변경합니다. AndroidManifest.xml, project.properties, res/values/google-services.xml이 포함되어 있어야 합니다.

Android 앱 빌드 도중 단일 dex 관련 문제

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

Cannot fit requested classes in a single dex file.

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

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

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

Player Settings 아래의 Custom Gradle Template이 사용 설정되어 있으면 mainTemplate.gradle을 수정합니다.
Android 스튜디오를 사용하여 내보낸 프로젝트를 빌드하는 경우 모듈 수준 build.gradle 파일을 수정합니다.

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

Unity 2017 및 Unity 2018에서 Android 빌드에 대한 자바 8 지원 및 디슈가링(Firebase Unity SDK 8.0.0 이상)

2021년 5월(Firebase BoM v28.0.0), Firebase에서는 모든 Android 라이브러리에 대한 디슈가링을 중지했습니다(출시 노트 참조). Firebase Unity SDK(8.0.0 이상)를 사용하여 Android 앱을 빌드하는 경우 다음과 같은 빌드 오류가 표시될 수 있습니다.

> Error while dexing.
 The dependency contains Java 8 bytecode. Please enable desugaring by adding the following to build.gradle

이 변경사항은 Unity 2017 및 Unity 2018의 Android 빌드에만 영향을 줍니다. 이후 버전의 Unity는 Gradle 빌드 파일에 compileOptions 블록을 기본적으로 추가합니다. Unity 2017 및 Unity 2018에서 이 빌드 오류를 수정하려면 다음 중 하나를 수행합니다.

Gradle 템플릿에 compileOptions 블록을 추가합니다.
1. 빌드 시스템으로 Gradle을 사용합니다.
2. Player Settings에서 Custom Gradle Template을 사용 설정합니다.
3. mainTemplate.gradle에 다음 줄을 추가합니다(Android 스튜디오 프로젝트 내보내기의 경우 모듈 수준 build.gradle).
```
android {
    compileOptions {
        sourceCompatibility 1.8
        targetCompatibility 1.8
    }
}
```
또는 Android 프로젝트의 minSdkVersion을 26 이상으로 높입니다.

Android 문제 해결 - 빌드 디슈가링 실패도 참조하세요.

CocoaPods를 사용하여 iOS용으로 빌드할 때 발생하는 문제

iOS용으로 빌드할 경우 언어 또는 UTF-8 인코딩 오류로 인해 CocoaPods 설치에 실패할 수 있습니다. 현재 이 문제를 해결하는 방법에는 여러 가지가 있습니다.

터미널에서 pod install을 직접 실행하고 결과로 생성되는 xcworkspace 파일을 엽니다.
CocoaPods를 1.10.2 버전으로 다운그레이드합니다. 이 문제는 버전 1.11 이상에서만 나타납니다.
~/.bash_profile 또는 이와 동등한 위치에 export LANG=en_US.UTF-8을 추가합니다.

Firebase Unity SDK의 버전을 업데이트하는 방법

Firebase Unity SDK의 버전을 업데이트하는 과정은 버전을 처음 가져온 방법에 따라 다릅니다. 다음은 두 가지 가져오기 방법입니다.

프로젝트의 Assets/ 디렉터리에 있는 .unitypackage 파일을 가져오기
Unity Package Manager(UPM)를 사용하여 가져오기
- Unity 2018.4 이상에서 패키지를 관리하는 데 권장되는 방법입니다.
- 이 방법을 사용하면 향후 버전 업데이트를 더 쉽게 수행하고 Assets/ 디렉터리를 깔끔하게 유지할 수 있습니다.

Unity 프로젝트에서는 한 가지 가져오기 방법으로 모든 Firebase 패키지를 관리해야 합니다. 아래 안내에 따라 개별 패키지 버전을 업데이트할 뿐 아니라 필요한 경우 패키지 관리를 UPM으로 마이그레이션(권장되는 가져오기 방법)할 수도 있습니다.

`.unitypackage` 파일로 `Assets/` 디렉터리에 가져온 패키지

Firebase 패키지가 Assets/ 디렉터리에 있는 경우 SDK 버전을 업데이트하는 두 가지 옵션이 있습니다.

옵션 1(권장): UPM을 사용하도록 마이그레이션(Unity 2018.4 이상에서 사용 가능)
- Firebase에서 제공하는 패키지 관리를 UPM으로 마이그레이션하는 방법을 따릅니다.
- 이 방법은 .unitypackage 워크플로를 계속 사용하는 것보다 더 많은 초기 설정이 필요하지만 이후 SDK 버전 업데이트가 용이해집니다.
옵션 2: .unitypackage 파일을 계속 사용하여 Assets/ 디렉터리로 가져오기
1. 업데이트된 버전의 각 패키지를 가져옵니다.
  
  Firebase 웹사이트에서 firebase_unity_sdk.zip을 다운로드할 경우 올바른 dotnet 폴더에서 모든 .unitypackages를 가져와야 합니다.
  - Unity 2019 이상을 사용하는 경우 dotnet4 폴더에서 가져옵니다.
  - 그렇지 않은 경우 Player Settings(플레이어 설정)에서 Scripting Runtime Version(스크립팅 런타임 버전)을 선택하고 '.NET 3.x'로 설정된 경우 dotnet3 폴더에서 가져옵니다.
2. 이전에 가져온 패키지 버전을 덮어쓰는 작업은 Firebase .unitypackages를 가져올 때 자동으로 포함되는 외부 종속 항목 관리자에 의해 자동으로 처리됩니다.
  
  하지만 이 자동 프로세스가 실패하는 경우에만 다음 폴더를 수동으로 삭제한 다음 위의 가져오기 단계를 다시 시도해야 합니다.
  - Assets/Editor Default Resources/Firebase
  - Assets/ExternalDependencyManager
  - Assets/Firebase
  - Assets/Parse
  - Assets/Plugins/iOS/Firebase

UPM에서 관리하는 패키지

Firebase 패키지를 UPM에서 관리하는 경우 최신 SDK 버전을 .tgz로 가져옵니다. 가져오기를 수행하면 이전 버전을 자동으로 덮어씁니다.