Начните работу с API Ambient

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

Поток Ambient API

Вот как работает Ambient API для подключения к устройству, а затем для получения и отображения медиафайлов:

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

2. Инициируйте авторизацию OAuth 2.0 (и при необходимости создайте устройство): Запустите процесс авторизации OAuth 2.0 для телевизоров и устройств с ограниченным набором входных данных, запросив код авторизации.

   Примечание: API Ambient поддерживает возможность включения параметра state в запрос на авторизацию. Это укажет API Ambient на необходимость попытки создания нового устройства после успешной авторизации.

3. Создание нового устройства: Ваше приложение создает устройство в учетной записи Google Фото пользователя, вызывая функцию CreateDevice и указывая действительный UUID версии 4.

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

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

5. Poll for mediaSourcesSet : Your application should periodically call the GetDevice method, providing the deviceId , to check the status of the ambient device. Monitor the mediaSourcesSet field in the AmbientDevice response. It will initially be false.

   После того как пользователь успешно выберет источники мультимедиа в приложении Google Фото, значение этого поля изменится на «истина».

   В ответе 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 если достигнуты лимиты устройств.

В руководстве по просмотру и извлечению медиафайлов содержится дополнительная информация, в том числе сведения о политике контента и фильтрации .

Следующие шаги

• Настройте приложение: убедитесь, что у вас есть необходимые учетные данные и что ваше приложение настроено для OAuth 2.0 для телевизоров и устройств с ограниченным набором входных данных .
• Ознакомьтесь со справочной документацией по API Ambient: изучите подробную справочную документацию по всем доступным методам, параметрам запроса и ответа, а также кодам ошибок.