Начало работы с Ambient API

Ambient API позволяет подключать устройства к аккаунту Google Фото пользователя и показывать на них выбранные фотографии.

Процесс работы Ambient API

Ниже описано, как Ambient API подключает устройство, а затем получает и показывает мультимедийные объекты.

  1. Проверка наличия устройства (рекомендуется). Перед созданием нового устройства рекомендуется проверить, существует ли уже устройство для текущего пользователя. Ваше приложение должно поддерживать сопоставление между внутренним идентификатором пользователя и предоставленным Google идентификатором deviceId для всех устройств, созданных через ваше приложение. Если для пользователя найден идентификатор deviceId, вы можете обновить его токен авторизации (если это необходимо).

  2. Инициируйте авторизацию OAuth 2.0. Начните процесс OAuth 2.0 для телевизоров и устройств с ограниченными возможностями ввода, запросив код авторизации.

  3. Создание устройства. Приложение создает устройство в аккаунте Google Фото пользователя, вызывая CreateDevice и предоставляя действительный UUID версии 4.

    После успешного создания устройства API вернет объект AmbientDevice, содержащий назначенный Google deviceId. Ваше приложение должно сохранять этот deviceId и связывать его с пользователями.

  4. Покажите settingsUri. Объект AmbientDevice включает settingsUri. Покажите пользователю этот URI, обычно в виде QR-кода, который можно отсканировать с помощью мобильного устройства. Этот URI направляет пользователя в приложение "Google Фото", где он может настроить источники медиаконтента (например, альбомы), которые хочет показывать на устройстве в режиме заставки.

  5. Опрос mediaSourcesSet. Приложение должно периодически вызывать метод GetDevice, предоставляя deviceId, чтобы проверять статус устройства Ambient. Отслеживайте поле mediaSourcesSet в ответе AmbientDevice. Изначально оно будет иметь значение false.

    Когда пользователь выберет источники медиафайлов в приложении "Google Фото", значение этого поля изменится на true.

    Ответ AmbientDevice содержит pollingConfig с pollInterval, который следует использовать в качестве ориентира для частоты опросов.

  6. Получение мультимедийных объектов. Если mediaSourcesSet возвращает значение true, ваше приложение может начать получать мультимедийные объекты, выбранные пользователем.

    Вызовите метод ListMediaItems, указав deviceId. API вернет объект ListMediaItemsResponse, содержащий список объектов AmbientMediaItem. Каждый объект AmbientMediaItem содержит такие сведения, как id, createTime и объект MediaFile с дополнительными метаданными. MediaFile содержит baseUrl, который можно использовать для получения фактических байтов мультимедийного объекта. Дополнительные сведения о параметрах baseUrl можно найти в руководстве Как получить список мультимедийных объектов и извлечь их.

  7. Показ медиаобъектов. Используйте baseUrl из MediaFile, чтобы скачать и показать медиаконтент на устройстве в режиме фоторамки.

Важная информация

Ограничения на количество устройств и управление ими:

  • Ограничения на количество устройств. Учитывайте, что каждый пользователь вашего приложения может использовать не более 100 устройств.
  • Действия на устройстве и токены. Вам нужно будет управлять жизненным циклом устройств и токенами авторизации пользователей. Учитывайте, как долго устройства остаются активными и как вы будете обрабатывать обновление токенов или повторную авторизацию, если устройство станет неактивным или срок действия токена истечет.

Дополнительную информацию можно найти в руководстве Создание устройств и управление ими.

Работа с мультимедийными объектами:

  • Использование мультимедийных объектов. Узнайте, как правильно получать и обрабатывать контент мультимедийных объектов с помощью baseUrl, включая необходимую аутентификацию и параметры.
  • Обработка ошибок. Реализуйте надежную обработку ошибок для вызовов API, в том числе в таких сценариях, как NOT_FOUND для устройств, FAILED_PRECONDITION, если не заданы источники мультимедиа, и RESOURCE_EXHAUSTED, если достигнуты ограничения на количество устройств.

Дополнительную информацию, в том числе о правилах в отношении контента и фильтрации, можно найти в руководстве Как получить список мультимедийных объектов и извлечь их.

Дальнейшие действия