APK 확장 파일APK Expansion Files

일부 애플리케이션(예: 일부 게임)의 경우 Google Play에서 정한 Android 최대 앱 크기 제한에서 제공할 수 있는 것보다 많은 리소스와 자산이 필요합니다.Some applications (some games, for instance) require more resources and assets than can be provided in the maximum Android app size limit imposed by Google Play. 이 제한은 APK가 대상으로 하는 Android 버전에 다라 다릅니다.This limit depends on the version of Android that your APK is targeted for:

  • Android 4.0 이상을 대상으로 하는 APK의 경우 100MB(API 수준 14 이상)100MB for APKs that target Android 4.0 or higher (API level 14 or higher).
  • Android 3.2 이하를 대상으로 하는 APK의 경우 50MB(API 수준 13 이상)50MB for APKs that target Android 3.2 or lower (API level 13 or higher).

이 제한을 극복하기 위해 Google Play는 APK와 함께 두 확장 파일을 호스트 및 배포하여 애플리케이션이 간접적으로 이 제한을 넘을 수 있게 합니다.To overcome this limitation, Google Play will host and distribute two expansion files to go along with an APK, allowing an application to indirectly exceed this limit.

대부분의 디바이스에서 애플리케이션이 설치되면 확장 파일이 APK와 함께 다운로드되며 디바이스의 공유 스토리지 위치(SD 카드나 USB 마운트 가능 파티션)에 스토리지됩니다.On most devices, when an application is installed, expansion files will be downloaded along with the APK and will be saved to the shared storage location (the SD card or the USB-mountable partition) on the device. 일부 구형 디바이스에서는 확장 파일이 APK와 함께 자동으로 설치되지 않을 수 있습니다.On a few older devices, the expansion files may not automatically install with the APK. 이 경우 애플리케이션 안에 사용자가 최초로 애플리케이션을 실행할 때 확장 파일을 다운로드하는 코드가 포함되어야 합니다.In these situations, it is necessary for the application to contain code that will download the expansion files when the user first runs the applications.

확장 파일은 불투명 이진 BLOB(obb) 으로 간주되며 최대 2GB 크기가 가능합니다.Expansion files are treated as opaque binary blobs (obb) and may be up to 2GB in size. Android는 이러한 파일을 다운로드한 후 특별한 처리를 수행하지 않으며 –이러한 파일은 애플리케이션에 적합한 어느 형식이나 가능합니다.Android does not perform any special processing on these files after they are downloaded – the files can be in any format that is appropriate for the application. 개념적으로 확장 파일에 권장되는 방식은 다음과 같습니다.Conceptually, the recommended approach to expansion files is as follows:

  • 기본 확장 – 이 파일은 APK 크기 제한에 맞지 않는 리소스 및 자산을 위한 기본 확장 파일입니다.Main expansion – This file is the primary expansion file for resources and assets that will not fit in the APK size limit. 기본 확장 파일은 애플리케이션에 필요하며 거의 업데이트되지 않는 기본 자산을 포함해야 합니다.The main expansion file should contain the primary assets that an application needs and should rarely be updated.
  • 패치 확장 – 기본 확장 파일에 대한 소규모 업데이트용입니다.Patch expansion – This is intended for small updates to the main expansion file. 이 파일은 업데이트될 수 있습니다.This file can be updated. 이 파일에서 필요한 패치나 업데이트를 수행하는 것은 애플리케이션이 담당합니다.It is the responsibility of the application to perform any necessary patches or updates from this file.

확장 파일은 APK 업로드와 동시에 업로드해야 합니다.The expansion files must be uploaded at the same time as the APK is uploaded. Google Play에서는 기존 APK에 확장 파일을 업로드하거나 기존 APK를 업데이트하는 것은 허용되지 않습니다.Google play does not allow an expansion file to be uploaded to an existing APK or for existing APKs to be updated. 확장 파일 업데이트가 필요한 경우 새 APK를 업데이트된 versionCode와 함께 업로드해야 합니다.If it is necessary to update an expansion file, then a new APK must be uploaded with the versionCode updated.

확장 파일 스토리지Expansion File Storage

파일이 디바이스에 다운로드되면 shared-store/Android/obb/package-name 에 저장됩니다.When the files are downloaded to a device, they will be stored in shared-store/Android/obb/package-name:

  • shared-storeAndroid.OS.Environment.ExternalStorageDirectory에서 지정한 디렉터리입니다.shared-store – This is the directory specified by Android.OS.Environment.ExternalStorageDirectory .
  • package-name – 애플리케이션의 Java 스타일 패키지 이름입니다.package-name – This is the application's Java-style package name.

다운로드 후에는 확장 파일을 디바이스의 위치에서 이동, 변경, 이름 변경 또는 삭제할 수 없습니다.Once downloaded, expansion files should not be moved, altered, renamed, or deleted from their location on the device. 이렇게 하면 확장 파일을 다시 다운로드하며 구 파일이 삭제됩니다.To do so will cause the expansion files to be downloaded again, and the old file(s) will be deleted. 또한 확장 파일 디렉터리에는 확장 팩 파일만 포함되어야 합니다.Additionally, the expansion file directory should contain only the expansion pack files.

확장 파일은 콘텐츠에 대한 보안이나 보호를 제공하지 않으므로 – 다른 애플리케이션이나 사용자가 공유 스토리지에 저장된 모든 파일에 액세스할 수 있습니다.Expansion files offer no security or protection around their content – other applications or users may access any files saved on the shared storage.

확장 파일의 압축을 풀어야 할 경우 압축을 푼 파일은 Android.OS.Environment.ExternalStorageDirectory의 디렉터리 같은 별도의 디렉터리에 저장해야 합니다.If it is necessary to unpack an expansion file, the unpacked files should be stored in a separate directory, such as one in Android.OS.Environment.ExternalStorageDirectory.

확장 파일에서 파일 압축을 푸는 또 다른 방법은 확장 파일에서 직접 자산이나 리소스를 읽는 것입니다.An alternative to extracting files from an expansion file is to read the assets or resources directly from the expansion file. 확장 파일은 적합한 ContentProvider에 사용할 수 있는 zip 파일 수준입니다.The expansion file is nothing more than a zip file that can be used with an appropriate ContentProvider. Android.Play.ExpansionLibrary에 어셈블리 System.IO.Compression.Zip이 포함되며 여기에는 일부 미디어 파일에 대한 직접 액세스를 허용하는 ContentProvider가 포함됩니다.The Android.Play.ExpansionLibrary contains an assembly, System.IO.Compression.Zip, which includes a ContentProvider that will allow for direct file access to some media files. 미디어 파일을 zip 파일로 묶으면 미디어 재생 호출에서 zip 파일 압축을 풀지 않고도 직접 zip의 파일을 사용할 수 있습니다.If media files are being packaged into a zip file, media playback calls may directly use files in the zip without having to unpack the zip file. 미디어 파일은 zip 파일에 추가될 때 압축되어서는 안 됩니다.The media files should not be compressed when added to the zip file.

파일 이름 형식FileName Format

확장 파일을 다운로드하면 Google Play는 다음 구성표를 사용하여 확장 이름을 지정합니다.When the expansion files are downloaded, Google Play will use the following scheme to name the expansion:

[main|patch].<expansion-version>.<package-name>.obb

이 스키마의 세 가지 구성 요소는 다음과 같습니다.The three components of this scheme are:

  • main 또는 patch – 기본 또는 패치 확장 파일인지 여부를 지정합니다.main or patch – This specifies whether this is the main or patch expansion file. 각각 하나만 있어야 합니다.There can be only one of each.
  • <expansion-version> – 파일이 처음 연결된 APK의 versionCode에 일치하는 정수입니다.<expansion-version> – This is an integer that matches the versionCode of the APK that the file was first associated with.
  • <package-name>– 애플리케이션의 Java 스타일 패키지 이름입니다.<package-name> – This is the application's Java-style package name.

예를 들어, APK 버전이 21이고 패키지 이름이 mono.samples.helloworld이면 기본 확장 파일의 이름은 main.21.mono.samples.helloworld가 됩니다.For example, if the APK version is 21, and the package name is mono.samples.helloworld, the main expansion file will be named main.21.mono.samples.helloworld.

다운로드 프로세스Download Process

Google Play에서 애플리케이션을 설치할 때 확장 파일이 APK와 함께 다운로드 및 저장되어야 합니다.When an application is installed from Google Play, the expansion files should be downloaded and saved along with the APK. 특정 상황에서 이것이 발생하지 않거나 확장 파일이 삭제될 수 있습니다.In certain situations this may not happen, or expansion files may be deleted. 이 문제를 처리하려면 필요한 경우 앱이 확장 파일이 존재하는지 확인한 다음 다운로드해야 합니다.To handle this condition, an app needs to check to see whether the expansion files exist and then download them, if necessary. 다음 순서도는 이 프로세스의 권장 워크플로를 나타냅니다.The following flowchart displays the recommended workflow of this process:

APK 확장 순서도APK expansion flowchart

애플리케이션이 시작되면 적합한 확장 파일이 현재 디바이스에 있는지 확인하는 검사를 수행해야 합니다.When an application starts up, it should check to see if the appropriate expansion files exist on the current device. 없으면 애플리케이션이 Google Play의 애플리케이션 라이선스에서 요청해야 합니다.If they do not, then the application must make a request from Google Play’s Application Licensing. 이 검사는 LVL(라이선스 확인 라이브러리) 를 통해 이루어지며 무료 및 라이선스 애플리케이션 모두에 대해 수행되야 합니다.This check is made by using the License Verification Library (LVL), and must be made for both free and licensed applications. LVL은 주로 유료 애플리케이션에서 라이선스 제한을 적용하기 위해 사용됩니다.The LVL is primarily used by paid applications to enforce license restrictions. 그러나 Google은 확장 라이브러리에도 이를 사용할 수 있게 LVL을 확장하고 있습니다.However, Google has extended the LVL so that it can be used with expansion libraries as well. 무료 애플리케이션은 LVL 검사를 수행해야 하지만 라이선스 제한은 무시할 수 있습니다.Free applications have to perform the LVL check, but can ignore the license restrictions. LVL 요청은 애플리케이션에서 요구하는 확장 파일에 관한 다음 정보를 제공하기 위한 것입니다.The LVL request is responsible for providing the following information about the expansion files that the application requires:

  • 파일 크기 – 확장 파일의 파일 크기는 정확한 확장 파일을 이미 다운로드했는지 여부를 판단하기 위한 검사의 일부로 사용됩니다.File Size – The file sizes of the expansion files are used as part of the check that determines whether or not the correct expansion files have already been downloaded.
  • 파일 이름– 확장 팩을 저장해야 하는 파일 이름(현재 디바이스의)입니다.Filenames – This is the file name (on the current device) to which the expansion packs must be saved.
  • 다운로드 URL – 확장 팩을 다운로드하는 데 사용하는 URL입니다.URL for Download – The URL that should be used to download the expansion packs. 다운로드마다 고유하며 제공 직후 만료됩니다.This is unique for every download and will expire shortly after it is provided.

LVL 검사가 수행된 후 애플리케이션은 확장 파일을 다운로드하게 되는데 다운로드의 일부로 다음 사항을 고려합니다.After the LVL check has been performed, the application should download the expansion files, taking into consideration the following points as part of the download:

  • 디바이스에 확장 파일 저장을 위한 공간이 부족할 수 있습니다.The device may not have enough space to store the expansion files.
  • Wi-Fi를 사용할 수 없는 경우 사용자는 원치 않는 데이터 요금이 발생하지 않게 다운로드를 일시 중지하거나 취소할 수 있어야 합니다.If Wi-Fi is not available, then the user should be allowed to pause or cancel the download to prevent unwanted data charges.
  • 확장 파일은 사용자 작업을 차단하지 않기 위해 백그라운드에서 다운로드됩니다.The expansion files are downloaded in the background to avoid blocking user interactions.
  • 다운로드가 백그라운드에서 수행되는 동안 진행률 표시기가 나타나야 합니다.While the download is occurring in the background, a progress indicator should be displayed.
  • 다운로드하는 동안 발생하는 오류는 정상적으로 처리되며 복구할 수 있습니다.Errors that occur during the download are gracefully handled and recoverable.

아키텍처 개요Architectural Overview

기본 활동이 시작되면 확장 파일이 다운로드되었는지 검사합니다.When the main activity starts, it checks to see if the expansion files are downloaded. 파일이 다운로드된 경우 파일에서 유효성을 검사합니다.If the files are downloaded, they must be checked for validity.

확장 파일을 다운로드하지 않았거나 현재 파일이 무효한 경우 새 확장 파일을 다운로드해야 합니다.If the expansion files have not been downloaded or if the current files are invalid, then new expansion files must be downloaded. 바인딩된 서비스가 애플리케이션의 일부로 만들어집니다.A bounded service is created as part of the application. 애플리케이션의 기본 활동이 시작되면 바인딩된 서비스를 통해 Google 라이선스 서비스에 대한 검사를 수행하여 확장 파일 이름과 다운로드할 파일의 URL을 확인합니다.When the main activity of the application is started, it uses the bounded service to perform a check against the Google Licensing services to find out the expansion file names and the URL of the files to download. 그런 다음 바인딩된 서비스가 백그라운드 스레드에 파일을 다운로드합니다.The bounded service will then download the files on a background thread.

확장 파일을 애플리케이션에 통합하는 데 필요한 작업을 간편하게 하기 위해 Google에서는 몇 가지 Java 라이브러리를 제작했습니다.To ease the effort required to integrate expansion files into an application, Google created several libraries in Java. 이 라이브러리는 다음과 같습니다.The libraries in question are:

  • Downloader 라이브러리– 애플리케이션에서 확장 파일을 통합하는 데 필요한 작업을 줄여 주는 라이브러리입니다.Downloader Library – This is a library that reduces the effort required to integrate expansion files in an application. 이 라이브러리는 백그라운드 서비스에 확장 파일을 다운로드하고, 사용자 알림을 표시하며, 네트워크 연결 문제를 처리하고, 다운로드를 재개하는 등의 작업을 수행합니다.The library will download the expansion files in a background service, display user notifications, handle network connectivity issues, resume downloads, etc.
  • LVL(라이선스 확인 라이브러리) – 애플리케이션 라이선스 서비스에 대한 호출을 수행 및 처리하기 위한 라이브러리입니다.License Verification Library (LVL) – A library for making and processing the calls to the Application Licensing services. 해당 디바이스에서 애플리케이션의 사용 권한이 있는지 확인하기 위한 라이선스 검사를 수행하는 데도 사용됩니다.It can also be used to perform licensing checks, to see if the application is authorized for use on the device.
  • APK 확장 Zip 라이브러리(선택 사항) – 확장 파일이 zip 파일 형식인 경우 이 라이브러리가 콘텐츠 공급자 역할을 하며 애플리케이션이 zip 파일 확장 없이 zip 파일에서 직접 리소스와 자산을 읽을 수 있게 합니다.APK Expansion Zip Library (optional) – If the expansion files are in a zip file, this library will act as a content provider and allow an application to read resources and assets directly from the zip file without having to expand the zip file.

이 라이브러리는 C#에 이식되었으며 Apache 2.0 라이선스에서 사용할 수 있습니다.These libraries have been ported to C# and are available under the Apache 2.0 license. 확장 파일을 기존 애플리케이션에 신속하게 통합할 수 있게 이 라이브러리를 기존 Xamarin.Android 애플리케이션에 추가할 수 있습니다.To quickly integrate expansion files into an existing application, these libraries can be added to an existing Xamarin.Android application. 이 코드는 GitHub의 Android.Play.ExpansionLibrary에서 제공합니다.The code is available at the Android.Play.ExpansionLibrary on GitHub.