Как создать облачное приложение для медиафайлов на Android

Поставщик облачных медиафайлов предоставляет дополнительный облачный медиаконтент для инструмента выбора фотографий Android. Пользователи могут выбирать фото и видео, предоставленные поставщиком облачного хранилища, когда приложение запрашивает медиафайлы с помощью ACTION_PICK_IMAGES или ACTION_GET_CONTENT. Поставщик облачного медиаконтента также может предоставлять информацию об альбомах, которые можно просматривать в окне выбора фотографий Android.

Подготовка

Прежде чем приступить к созданию облачного поставщика медиаконтента, учтите следующее:

Требования

В рамках пилотной программы Android приложения, назначенные OEM-производителями, могут стать поставщиками облачных медиафайлов. В настоящее время в программе могут участвовать только приложения, номинированные OEM-производителями. Каждый OEM-производитель может номинировать до трех приложений. После одобрения эти приложения становятся доступны в качестве поставщиков облачных медиафайлов на любом устройстве Android с GMS, на котором они установлены.

На сервере Android хранится список всех подходящих поставщиков облачных сервисов. Каждый OEM-производитель может выбрать поставщика облачных сервисов по умолчанию, используя настраиваемый оверлей. Номинированные приложения должны соответствовать всем техническим требованиям и пройти все проверки качества. Чтобы узнать больше о процессе и требованиях пилотной программы для поставщиков облачных медиасервисов, заполните форму запроса.

Решите, нужно ли вам создавать поставщика облачного медиаконтента

Поставщиками облачного медиаконтента могут быть приложения или сервисы, которые пользователи выбирают в качестве основного источника для резервного копирования и получения фотографий и видео из облака. Если в вашем приложении есть библиотека полезного контента, но оно не используется для хранения фотографий, рекомендуем создать поставщика документов.

Один активный поставщик облачных сервисов на профиль

Для каждого профиля Android можно выбрать только одного поставщика облачных медиасервисов. Пользователи могут в любой момент удалить или изменить выбранное приложение поставщика облачных медиа в настройках инструмента выбора фотографий.

По умолчанию инструмент выбора фотографий Android пытается выбрать поставщика облачных сервисов автоматически.

  • Если на устройстве есть только один подходящий поставщик облачных сервисов, он будет выбран автоматически.
  • Если на устройстве есть несколько подходящих поставщиков облачных сервисов и один из них совпадает с выбранным по умолчанию поставщиком OEM, то будет выбран поставщик OEM.

  • Если на устройстве несколько подходящих облачных сервисов и ни один из них не совпадает с выбранным OEM-производителем по умолчанию, приложение не будет выбрано.

Создайте облачный сервис для медиафайлов

На схеме ниже показана последовательность событий до и во время выбора фотографий в приложении Android, инструменте выбора фотографий Android, MediaProvider на локальном устройстве и CloudMediaProvider.

Диаграмма последовательности, показывающая поток от выбора фотографий до поставщика облачных медиафайлов
Рисунок 1. Диаграмма последовательности событий во время сеанса выбора фотографий.
  1. Система инициализирует выбранного пользователем поставщика облачных сервисов и периодически синхронизирует метаданные медиафайлов с серверной частью инструмента "Выбор фотографий" в Android.
  2. Когда приложение Android запускает инструмент выбора фотографий, перед показом объединенной сетки локальных или облачных элементов инструмент выбора фотографий выполняет инкрементную синхронизацию с поставщиком облачных услуг, чувствительную к задержке, чтобы обеспечить максимально актуальные результаты. После получения ответа или по истечении срока в сетке выбора фотографий теперь отображаются все доступные фотографии, объединяя те, которые хранятся локально на вашем устройстве, с теми, которые синхронизированы из облака.
  3. Когда пользователь прокручивает экран, инструмент выбора фотографий получает уменьшенные изображения медиафайлов от поставщика облачного хранилища и показывает их в интерфейсе.
  4. Когда пользователь завершает сеанс и результаты включают объект из облака, инструмент выбора фотографий запрашивает дескрипторы файлов для контента, генерирует URI и предоставляет вызывающему приложению доступ к файлу.
  5. Теперь приложение может открывать URI и имеет доступ только для чтения к медиаконтенту. По умолчанию конфиденциальные метаданные удаляются. Для координации обмена данными между приложением Android и поставщиком облачных медиафайлов в инструменте выбора фотографий используется файловая система FUSE.

Распространенные проблемы

При реализации этой функции необходимо учитывать следующее:

Избегайте дублирования файлов

Поскольку у инструмента выбора фотографий Android нет возможности проверить состояние медиафайлов в облаке, CloudMediaProvider должен предоставить MEDIA_STORE_URI в строке курсора любого файла, который существует как в облаке, так и на локальном устройстве. В противном случае пользователь увидит дубликаты файлов в инструменте выбора фотографий.

Оптимизация размеров изображений для предварительного просмотра

Очень важно, чтобы файл, возвращаемый из onOpenPreview, не был изображением в полном разрешении и соответствовал запрашиваемому Size. Слишком большое изображение будет долго загружаться, а слишком маленькое может выглядеть размытым или пикселизированным на экранах некоторых устройств.

Правильная ориентация ручки

Если значки, возвращаемые в onOpenPreview, не содержат данных EXIF, они должны возвращаться в правильной ориентации, чтобы избежать неправильного поворота значков в сетке предварительного просмотра.

Защита от несанкционированного доступа

Прежде чем возвращать данные вызывающему объекту из ContentProvider, проверьте наличие разрешения MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION. Это заблокирует доступ неавторизованных приложений к облачным данным.

Класс CloudMediaProvider

Класс CloudMediaProvider, производный от android.content.ContentProvider, включает методы, подобные показанным в следующем примере:

Kotlin

abstract class CloudMediaProvider : ContentProvider() {

    @NonNull
    abstract override fun onGetMediaCollectionInfo(@NonNull bundle: Bundle): Bundle

    @NonNull
    override fun onQueryAlbums(@NonNull bundle: Bundle): Cursor = TODO("Implement onQueryAlbums")

    @NonNull
    abstract override fun onQueryDeletedMedia(@NonNull bundle: Bundle): Cursor

    @NonNull
    abstract override fun onQueryMedia(@NonNull bundle: Bundle): Cursor

    @NonNull
    abstract override fun onOpenMedia(
        @NonNull string: String,
        @Nullable bundle: Bundle?,
        @Nullable cancellationSignal: CancellationSignal?
    ): ParcelFileDescriptor

    @NonNull
    abstract override fun onOpenPreview(
        @NonNull string: String,
        @NonNull point: Point,
        @Nullable bundle: Bundle?,
        @Nullable cancellationSignal: CancellationSignal?
    ): AssetFileDescriptor

    @Nullable
    override fun onCreateCloudMediaSurfaceController(
        @NonNull bundle: Bundle,
        @NonNull callback: CloudMediaSurfaceStateChangedCallback
    ): CloudMediaSurfaceController? = null
}

Java

public abstract class CloudMediaProvider extends android.content.ContentProvider {

  @NonNull
  public abstract android.os.Bundle onGetMediaCollectionInfo(@NonNull android.os.Bundle);

  @NonNull
  public android.database.Cursor onQueryAlbums(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.database.Cursor onQueryDeletedMedia(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.database.Cursor onQueryMedia(@NonNull android.os.Bundle);

  @NonNull
  public abstract android.os.ParcelFileDescriptor onOpenMedia(@NonNull String, @Nullable android.os.Bundle, @Nullable android.os.CancellationSignal) throws java.io.FileNotFoundException;

  @NonNull
  public abstract android.content.res.AssetFileDescriptor onOpenPreview(@NonNull String, @NonNull android.graphics.Point, @Nullable android.os.Bundle, @Nullable android.os.CancellationSignal) throws java.io.FileNotFoundException;

  @Nullable
  public android.provider.CloudMediaProvider.CloudMediaSurfaceController onCreateCloudMediaSurfaceController(@NonNull android.os.Bundle, @NonNull android.provider.CloudMediaProvider.CloudMediaSurfaceStateChangedCallback);
}

Класс CloudMediaProviderContract

Помимо основного класса реализации CloudMediaProvider, в инструменте выбора фотографий Android есть класс CloudMediaProviderContract. Этот класс описывает совместимость между инструментом выбора фотографий и поставщиком облачного медиаконтента, включая такие аспекты, как MediaCollectionInfo для операций синхронизации, ожидаемые столбцы Cursor и дополнительные элементы Bundle.

Kotlin

object CloudMediaProviderContract {

    const val EXTRA_ALBUM_ID = "android.provider.extra.ALBUM_ID"
    const val EXTRA_LOOPING_PLAYBACK_ENABLED = "android.provider.extra.LOOPING_PLAYBACK_ENABLED"
    const val EXTRA_MEDIA_COLLECTION_ID = "android.provider.extra.MEDIA_COLLECTION_ID"
    const val EXTRA_PAGE_SIZE = "android.provider.extra.PAGE_SIZE"
    const val EXTRA_PAGE_TOKEN = "android.provider.extra.PAGE_TOKEN"
    const val EXTRA_PREVIEW_THUMBNAIL = "android.provider.extra.PREVIEW_THUMBNAIL"
    const val EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED = "android.provider.extra.SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED"
    const val EXTRA_SYNC_GENERATION = "android.provider.extra.SYNC_GENERATION"
    const val MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION = "com.android.providers.media.permission.MANAGE_CLOUD_MEDIA_PROVIDERS"
    const val PROVIDER_INTERFACE = "android.content.action.CLOUD_MEDIA_PROVIDER"

    object MediaColumns {
        const val DATE_TAKEN_MILLIS = "date_taken_millis"
        const val DURATION_MILLIS = "duration_millis"
        const val HEIGHT = "height"
        const val ID = "id"
        const val IS_FAVORITE = "is_favorite"
        const val MEDIA_STORE_URI = "media_store_uri"
        const val MIME_TYPE = "mime_type"
        const val ORIENTATION = "orientation"
        const val SIZE_BYTES = "size_bytes"
        const val STANDARD_MIME_TYPE_EXTENSION = "standard_mime_type_extension"
        const val STANDARD_MIME_TYPE_EXTENSION_ANIMATED_WEBP = 3 // 0x3
        const val STANDARD_MIME_TYPE_EXTENSION_GIF = 1 // 0x1
        const val STANDARD_MIME_TYPE_EXTENSION_MOTION_PHOTO = 2 // 0x2
        const val STANDARD_MIME_TYPE_EXTENSION_NONE = 0 // 0x0
        const val SYNC_GENERATION = "sync_generation"
        const val WIDTH = "width"
    }

    object AlbumColumns {
        const val DATE_TAKEN_MILLIS = "date_taken_millis"
        const val DISPLAY_NAME = "display_name"
        const val ID = "id"
        const val MEDIA_COUNT = "album_media_count"
        const val MEDIA_COVER_ID = "album_media_cover_id"
    }

    object MediaCollectionInfo {
        const val ACCOUNT_CONFIGURATION_INTENT = "account_configuration_intent"
        const val ACCOUNT_NAME = "account_name"
        const val LAST_MEDIA_SYNC_GENERATION = "last_media_sync_generation"
        const val MEDIA_COLLECTION_ID = "media_collection_id"
    }
}

Java

public final class CloudMediaProviderContract {

  public static final String EXTRA_ALBUM_ID = "android.provider.extra.ALBUM_ID";
  public static final String EXTRA_LOOPING_PLAYBACK_ENABLED = "android.provider.extra.LOOPING_PLAYBACK_ENABLED";
  public static final String EXTRA_MEDIA_COLLECTION_ID = "android.provider.extra.MEDIA_COLLECTION_ID";
  public static final String EXTRA_PAGE_SIZE = "android.provider.extra.PAGE_SIZE";
  public static final String EXTRA_PAGE_TOKEN = "android.provider.extra.PAGE_TOKEN";
  public static final String EXTRA_PREVIEW_THUMBNAIL = "android.provider.extra.PREVIEW_THUMBNAIL";
  public static final String EXTRA_SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED = "android.provider.extra.SURFACE_CONTROLLER_AUDIO_MUTE_ENABLED";
  public static final String EXTRA_SYNC_GENERATION = "android.provider.extra.SYNC_GENERATION";
  public static final String MANAGE_CLOUD_MEDIA_PROVIDERS_PERMISSION = "com.android.providers.media.permission.MANAGE_CLOUD_MEDIA_PROVIDERS";
  public static final String PROVIDER_INTERFACE = "android.content.action.CLOUD_MEDIA_PROVIDER";
}

// Columns available for every media item
public static final class CloudMediaProviderContract.MediaColumns {

  public static final String DATE_TAKEN_MILLIS = "date_taken_millis";
  public static final String DURATION_MILLIS = "duration_millis";
  public static final String HEIGHT = "height";
  public static final String ID = "id";
  public static final String IS_FAVORITE = "is_favorite";
  public static final String MEDIA_STORE_URI = "media_store_uri";
  public static final String MIME_TYPE = "mime_type";
  public static final String ORIENTATION = "orientation";
  public static final String SIZE_BYTES = "size_bytes";
  public static final String STANDARD_MIME_TYPE_EXTENSION = "standard_mime_type_extension";
  public static final int STANDARD_MIME_TYPE_EXTENSION_ANIMATED_WEBP = 3; // 0x3
  public static final int STANDARD_MIME_TYPE_EXTENSION_GIF = 1; // 0x1 
  public static final int STANDARD_MIME_TYPE_EXTENSION_MOTION_PHOTO = 2; // 0x2 
  public static final int STANDARD_MIME_TYPE_EXTENSION_NONE = 0; // 0x0 
  public static final String SYNC_GENERATION = "sync_generation";
  public static final String WIDTH = "width";
}

// Columns available for every album item
public static final class CloudMediaProviderContract.AlbumColumns {

  public static final String DATE_TAKEN_MILLIS = "date_taken_millis";
  public static final String DISPLAY_NAME = "display_name";
  public static final String ID = "id";
  public static final String MEDIA_COUNT = "album_media_count";
  public static final String MEDIA_COVER_ID = "album_media_cover_id";
}

// Media Collection metadata that is cached by the OS to compare sync states.
public static final class CloudMediaProviderContract.MediaCollectionInfo {

  public static final String ACCOUNT_CONFIGURATION_INTENT = "account_configuration_intent";
  public static final String ACCOUNT_NAME = "account_name";
  public static final String LAST_MEDIA_SYNC_GENERATION = "last_media_sync_generation";
  public static final String MEDIA_COLLECTION_ID = "media_collection_id";
}

onGetMediaCollectionInfo

Метод onGetMediaCollectionInfo() используется операционной системой для оценки действительности кэшированных облачных медиаобъектов и определения необходимости синхронизации с поставщиком облачных медиа. Поскольку операционная система может часто вызывать onGetMediaCollectionInfo(), этот метод считается критически важным для производительности. Необходимо избегать длительных операций и побочных эффектов, которые могут негативно повлиять на производительность. Операционная система кеширует предыдущие ответы этого метода и сравнивает их с последующими, чтобы определить, какие действия нужно выполнить.

Kotlin

abstract fun onGetMediaCollectionInfo(extras: Bundle): Bundle

Java

@NonNull
public abstract Bundle onGetMediaCollectionInfo(@NonNull Bundle extras);

Возвращаемый пакет MediaCollectionInfo содержит следующие константы:

onQueryMedia

Метод onQueryMedia() используется для заполнения основной сетки фотографий в инструменте выбора фотографий в различных представлениях. Эти вызовы могут быть чувствительны к задержке и могут вызываться как часть фоновой упреждающей синхронизации или во время сеансов выбора фотографий, когда требуется состояние полной или инкрементной синхронизации. Интерфейс выбора фотографий не будет бесконечно ждать ответа, чтобы показать результаты, и может прервать эти запросы по тайм-ауту в целях пользовательского интерфейса. Возвращенный курсор все равно будет обработан в базе данных инструмента выбора фотографий для будущих сеансов.

Этот метод возвращает Cursor, представляющий все мультимедийные объекты в коллекции, которые могут быть отфильтрованы по дополнительным параметрам и отсортированы в обратном хронологическом порядке по MediaColumns#DATE_TAKEN_MILLIS (сначала самые новые).

Возвращаемый пакет CloudMediaProviderContract содержит следующие константы:

Облачный поставщик медиаконтента должен задать CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID как часть возвращаемого Bundle. Если не задать это значение, возникнет ошибка и возвращенный объект Cursor будет недействительным. Если поставщик облачного медиаконтента обработал какие-либо фильтры в предоставленных дополнительных данных, он должен добавить ключ в ContentResolver#EXTRA_HONORED_ARGS как часть возвращенного Cursor#setExtras.

onQueryDeletedMedia

Метод onQueryDeletedMedia() используется, чтобы удаленные объекты в облачном аккаунте правильно удалялись из пользовательского интерфейса выбора фотографий. Поскольку такие вызовы могут быть чувствительны к задержкам, они могут инициироваться в рамках:

  • Проактивная синхронизация в фоновом режиме
  • Сеансы выбора фотографий (когда требуется полная или инкрементная синхронизация).

Пользовательский интерфейс выбора фотографий обеспечивает удобство использования и не будет ждать ответа бесконечно. Чтобы обеспечить бесперебойную работу, могут возникать тайм-ауты. Все возвращенные Cursor будут по-прежнему обрабатываться в базе данных инструмента выбора фотографий для будущих сеансов.

Этот метод возвращает объект Cursor, представляющий все удаленные мультимедийные объекты во всей медиаколлекции в текущей версии поставщика, возвращенной методом onGetMediaCollectionInfo(). Эти объекты можно отфильтровать по дополнительным параметрам. Поставщик облачного хранилища должен задать CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID в возвращаемом объекте Cursor#setExtras. Если этого не сделать, возникнет ошибка и Cursor станет недействительным. Если поставщик обработал какие-либо фильтры в предоставленных дополнительных параметрах, он должен добавить ключ в ContentResolver#EXTRA_HONORED_ARGS.

onQueryAlbums

Метод onQueryAlbums() используется для получения списка альбомов, доступных у поставщика облачных сервисов, и связанных с ними метаданных. Дополнительную информацию можно найти в статье CloudMediaProviderContract.AlbumColumns.

Этот метод возвращает Cursor, представляющий все объекты альбома в медиаколлекции, которые могут быть отфильтрованы по предоставленным дополнительным параметрам и отсортированы в обратном хронологическом порядке AlbumColumns#DATE_TAKEN_MILLIS, начиная с самых последних объектов. Облачный поставщик медиаконтента должен задать CloudMediaProviderContract#EXTRA_MEDIA_COLLECTION_ID как часть возвращаемого Cursor. Если не задать это значение, возникнет ошибка и возвращенный объект Cursor будет недействительным. Если поставщик обработал какие-либо фильтры в предоставленных дополнительных данных, он должен добавить ключ в ContentResolver#EXTRA_HONORED_ARGS как часть возвращенного Cursor.

onOpenMedia

Метод onOpenMedia() должен возвращать полноразмерный медиафайл, идентифицированный предоставленным mediaId. Если этот метод блокируется при скачивании контента на устройство, периодически проверяйте предоставленный CancellationSignal, чтобы отменять брошенные запросы.

onOpenPreview

Метод onOpenPreview() должен возвращать значок указанного размера (size) для объекта с заданным идентификатором mediaId. Значок должен быть в исходном формате CloudMediaProviderContract.MediaColumns#MIME_TYPE и иметь гораздо более низкое разрешение, чем объект, возвращаемый методом onOpenMedia. Если этот метод заблокирован во время скачивания контента на устройство, периодически проверяйте предоставленный CancellationSignal, чтобы прерывать заброшенные запросы.

onCreateCloudMediaSurfaceController

Метод onCreateCloudMediaSurfaceController() должен возвращать объект CloudMediaSurfaceController, используемый для отрисовки предварительного просмотра медиаобъектов, или null, если отрисовка предварительного просмотра не поддерживается.

CloudMediaSurfaceController управляет отрисовкой предварительного просмотра мультимедийных объектов в заданных экземплярах Surface. Методы этого класса должны быть асинхронными и не должны блокироваться при выполнении тяжелых операций. Один экземпляр CloudMediaSurfaceController отвечает за отрисовку нескольких мультимедийных объектов, связанных с несколькими поверхностями.

CloudMediaSurfaceController поддерживает следующие обратные вызовы жизненного цикла: