Table of Contents

EasyAR Sense Unity Plugin 마이그레이션 가이드

이 문서는 이전 버전의 EasyAR Sense Unity Plugin에서 새 버전으로의 마이그레이션 방법을 설명합니다.

Compatibility notes

버전 4000부터 EasyAR Sense Unity Plugin은 Unity가 요구하는 패키지 버전 관리(Semantic Versioning 사용)를 따르며, 버전 번호를 통해 호환성을 판단할 수 있습니다.

4.7은 점진적 업데이트 버전으로, 4.7 버전 간에는 서로 호환되지 않습니다.

4.7 이전 버전에서는 세 번째 버전 번호만 이전 버전과의 호환성을 나타내며, 첫 두 버전 번호의 변경은 모두 호환되지 않음을 의미합니다. 예를 들어, 4.6.2는 4.6.1과 호환되지만, 4.6.0은 4.5.0과 호환되지 않습니다.

[!경고] tgz 파일을 수정하거나 압축 해제 후 전체 플러그인을 완전히 업데이트하지 않으면 호환성 문제가 발생할 수 있습니다.

일반 마이그레이션 가이드

새 버전으로 마이그레이션하려면 Package Manager window를 사용하여 이전 버전의 플러그인 패키지를 제거하고 새 패키지를 추가해야 합니다.

다음 단계를 따르는 것이 좋습니다:

  1. 사용 중인 Unity를 종료합니다.
  2. Unity가 애플리케이션 빌드 시 생성한 플랫폼 컴파일 디렉터리를 삭제합니다.
  3. Unity 프로젝트를 다시 열고 이전 버전의 EasyAR Sense Unity Plugin을 프로젝트에서 제거합니다.
  4. 새 버전의 EasyAR Sense Unity Plugin을 가져옵니다.

[!참고] 플러그인이 제공하는 샘플 파일은 버전 간 호환성을 보장하지 않습니다. 플러그인 업그레이드 후 프로젝트로 가져온 샘플이 제대로 작동하지 않을 수 있으므로, 이전 버전 샘플을 삭제한 후 작업하는 것이 좋습니다.

EasyAR에는 네이티브 라이브러리 파일이 포함되어 있습니다. 삭제 또는 교체 전에 라이브러리 함수를 실행한 경우(빌드 시에도 호출됨), 이러한 라이브러리 파일은 시스템에 의해 잠겨 삭제하거나 교체할 수 없습니다.

[!중요] 이전 버전을 삭제하기 전에 에디터에서 어떤 장면도 실행하지 않았거나 어떤 플랫폼으로도 애플리케이션을 빌드하지 않았는지 확인해야 합니다. 일반적으로 패키지를 삭제하거나 교체하기 전에 Unity를 종료하고 다시 열자마자 교체하는 것이 좋습니다.

새 버전 플러그인으로 다시 빌드하기 전에 Unity 빌드로 생성된 플랫폼 컴파일 디렉터리를 삭제해야 합니다. 여기에는 Android 빌드 시 생성된 Gradle 프로젝트 디렉터리와 iOS 빌드 시 생성된 Xcode 디렉터리가 포함됩니다.

[!팁] 일반적으로 이러한 디렉터리는 Unity 프로젝트의 Library 폴더 내에 있을 수 있습니다(예: Library/Bee/Android/Prj/IL2CPP/Gradle). 하지만 Unity 버전에 따라 다를 수 있습니다.

빌드한 경험이 있지만 해당 플랫폼 디렉터리를 찾을 수 없는 경우, 전체 Library 폴더를 삭제하는 것이 좋습니다.

마이그레이션 후 SchemaHashNotMatched 예외가 발생하면 일반적으로 두 가지 가능성이 있습니다.

  1. 앞서 설명한 작업이 올바르게 수행되지 않아 업그레이드가 실패하거나 불완전했거나, Unity가 생성한 컴파일 디렉터리가 올바르게 업데이트되지 않았습니다(참고: 수동으로 삭제하지 않았다면 오류가 발생할 가능성이 높음). 권장 단계를 따르거나 Library 캐시가 없는 프로젝트에서 다시 컴파일하는 것이 좋습니다.
  2. EasyAR의 tgz 파일을 수동으로 수정했거나 압축 해제 후 전체 플러그인을 완전히 업데이트하지 않았습니다. 이 경우 EasyAR는 사용성을 보장할 수 없으며, 올바른 패키지를 다시 다운로드하여 가져와야 합니다.

[!중요] EasyAR Sense 라이브러리 파일 및 라이브러리 파일이 패키징된 위치는 변경될 수 있으므로, Unity가 생성한 Gradle 또는 Xcode 프로젝트를 보존하는 경우 EasyAR.aar, libEasyAR.so, easyar.framework 등 EasyAR와 관련된 모든 파일을 미리 삭제해야 합니다.

버전 4001로 마이그레이션

[!팁] Mega 사용 시에만 비호환성 변경 사항이 있으며, 다른 기능 사용에는 영향을 미치지 않습니다.

버전 4000에서 4001로 마이그레이션할 때는 위의 일반 마이그레이션 가이드 외에도 다음 내용에 유의해야 합니다.

인터페이스 변경

기능 모듈 v4000 API v4001 API 사용 설명
Mega MegaTrackerFrameFilter.ResultPoseType.EnableLocalization MegaTrackerFrameFilter.EnableLocalization Mega 추적 프로세스 제어
Mega MegaTrackerFrameFilter.ResultPoseType.EnableStabilization - 기능 삭제됨

이전 버전 마이그레이션

4000 이전 버전에서 마이그레이션할 때는 다음 내용을 참조하세요:

관련 주제