Файлы расширения APKAPK Expansion Files

Для некоторых приложений (например, для некоторых игр) требуются дополнительные ресурсы и активы, которые могут быть предоставлены с учетом ограничения по максимальному размеру приложения Android, накладываемого Google Play.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. Это ограничение зависит от версии Android, для которой предназначен пакет APK:This limit depends on the version of Android that your APK is targeted for:

  • 100 МБ для пакетов APK, предназначенных для Android 4.0 или более поздних версий (API уровня 14 или выше);100MB for APKs that target Android 4.0 or higher (API level 14 or higher).
  • 50 МБ для пакетов APK, предназначенных для Android 3.2 или более ранних версий (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) и могут иметь размер до 2 ГБ.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:

  • Расширение main — это основной файл расширения для ресурсов, которые превышают ограничение размера пакета APK.Main expansion – This file is the primary expansion file for resources and assets that will not fit in the APK size limit. Файл расширения main должен содержать основные ресурсы, необходимые приложению, и редко обновляться.The main expansion file should contain the primary assets that an application needs and should rarely be updated.
  • Расширение patch — это расширение предназначено для небольших обновлений файла расширения main.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-store — это каталог, заданный свойством Android.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. Файл расширения — это не что иное, как ZIP-файл, который можно использовать с соответствующим ContentProvider.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-файле без распаковки архива.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> — это целое число, соответствующее versionCode пакета APK, с которым был связан файл.<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:

Блок-схема файлов расширения APKAPK 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 расширила возможности библиотеки, чтобы ее можно было также использовать с библиотеками расширения.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 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.
  • Библиотека ZIP-файла расширения APK (необязательная. — если файлы расширения упакованы в 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. Код доступен в Android.Play.ExpansionLibrary на сайте GitHub.The code is available at the Android.Play.ExpansionLibrary on GitHub.