Настройте свое приложение для Ambient API

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

Ваше приложение взаимодействует с Ambient API от имени пользователя Ambient API. Пользователь авторизует эти запросы API с помощью протокола OAuth 2.0 .

Идентификатор клиента OAuth 2.0 позволяет пользователям вашего приложения входить в систему, проходить аутентификацию и, таким образом, использовать Ambient API. Ambient API не поддерживает учетные записи служб; Чтобы использовать эти API, пользователи должны войти в действующую учетную запись Google.

Настройте свое приложение

Сначала включите API, затем запросите идентификатор клиента OAuth 2.0.

Включить API

Прежде чем вы сможете использовать Ambient API, вы должны включить его в своем проекте.

  1. Перейдите в консоль Google API .
  2. В строке меню выберите проект или создайте новый проект.
  3. Чтобы открыть один из API Google Фото, в меню навигации выберите API и службы > Библиотека .
  4. Найдите «Ambient API». Выберите Ambient API и нажмите «Включить» .

Запросить идентификатор клиента OAuth 2.0

Выполните следующие действия, чтобы запросить идентификатор клиента OAuth и настроить его для своего приложения. Ambient API использует OAuth 2.0 для приложений телевидения и устройств с ограниченным вводом .

  1. Перейдите в консоль Google API и выберите свой проект.
  2. В меню выберите API и службы > Учетные данные .

  3. На странице «Учетные данные» нажмите «Создать учетные данные» > «Идентификатор клиента OAuth» .

  4. Выберите тип приложения . В этом примере тип приложения — «Телевизоры и устройства ограниченного ввода» .

  5. Укажите имя вашего клиента OAuth 2.0 и нажмите «Создать» .

  6. В появившемся диалоговом окне клиента OAuth скопируйте следующее:

    • Идентификатор клиента
    • Секрет клиента

Ваше приложение может получить доступ к включенным API Google, используя эти значения.

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

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

Изменение идентификатора клиента

Доступ к ресурсам, созданным с помощью любого из API Google Фото, можно получить или изменить только с использованием исходного идентификатора клиента, использованного для их создания. Например, если вы создадите session в API Picker с определенным идентификатором клиента, а затем измените этот идентификатор клиента в своем приложении, ваше приложение потеряет доступ к любым ресурсам API, созданным с предыдущим идентификатором клиента.

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

Оптимизированный процесс аутентификации для Ambient API

Стандартный процесс аутентификации Ambient API требует, чтобы ваши пользователи отсканировали 2 QR-кода:

  • Первым войти в свою учетную запись Google (если они еще не вошли в систему).
  • Второй, который ссылается на недавно созданное устройство Ambient в их учетной записи Google Photos, где они могут выбирать мультимедийные элементы для отображения.

Оптимизированный процесс позволяет предоставить пользователям один QR-код, передав дополнительный параметр state при первоначальном вызове аутентификации.

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

Параметры
requestId

string

Необходимый. Уникальный идентификатор, предоставленный клиентом для этого запроса. Это используется для предотвращения дублирования ресурсов в случае сбоя сети.

Этот идентификатор должен иметь формат строки UUID (версия 4) и соответствовать следующим требованиям:

  • Не должно содержать никакой конфиденциальной идентификационной информации о пользователе.
  • Должно содержать 32 шестнадцатеричных символа, разделенных на пять групп, разделенных дефисами, в формате «хххххххх-хххх-хххх-хххх-хххххххххххх» (или 8-4-4-4-12).
displayName

string

Необязательный. Определяемое пользователем отображаемое имя для этого устройства.

Это будет видно пользователям в настройках приложения Google Photos, но редактироваться можно будет только через этот API.

Допустимые отображаемые имена должны содержать от 1 до 100 символов (включительно).

Например, см. следующий блок кода:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Успешный ответ будет включать в себя user_code и verification_url , которые вы показываете пользователю (скорее всего, в виде QR-кода), чтобы он мог перейти туда на отдельном устройстве. Включив параметр state , когда вы позже вызовете createDevice с помощью Ambient API, вы можете пропустить представление settingsUri во втором QR-коде, поскольку последний шаг в потоке OAuth будет автоматически перенаправляться в это место.

Для получения полной информации мы включили более подробное объяснение. Вы также можете просмотреть код в нашем примере приложения , чтобы увидеть пример использования параметра state как части OAuth для ограниченных устройств ввода с Ambient API.

Подробности об упрощенном процессе аутентификации

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

OAuth 2.0 для телевизоров и приложений с ограниченным вводом данных:

  1. Ваше приложение отправляет запрос на сервер авторизации Google, который определяет области, к которым ваше приложение будет запрашивать разрешение на доступ.
  2. Сервер отвечает несколькими фрагментами информации, используемыми на последующих этапах, такими как код устройства и код пользователя.
  3. Вы отображаете информацию, которую пользователь может ввести на отдельном устройстве для авторизации вашего приложения.
  4. Ваше приложение начинает опрашивать сервер авторизации Google, чтобы определить, авторизовал ли пользователь ваше приложение.
  5. Пользователь переключается на устройство с более широкими возможностями ввода, запускает веб-браузер, переходит по URL-адресу, отображаемому на шаге 3, и вводит код, который также отображается на шаге 3. Затем пользователь может предоставить (или запретить) доступ к вашему приложению.
  6. Следующий ответ на ваш запрос на опрос содержит токены, необходимые вашему приложению для авторизации запросов от имени пользователя. (Если пользователь отказал в доступе к вашему приложению, ответ не содержит токенов.)

Поток окружающего API:

  1. Проверьте наличие существующего токена OAuth и обновите его или запросите новый.
  2. После получения токена OAuth создайте новое устройство.
  3. Отобразите settingsUri пользователю и начните опрашивать устройство, пока mediaSourcesSet не вернет true.
  4. Пользователь переходит к settingsUri и выбирает фотографии, которыми он хочет поделиться с вашим приложением.
  5. Как только mediaSourcesSet вернет true, получите список mediaItems .
  6. Теперь вы можете начать слайд-шоу или другой интересный опыт.

Оба потока включают в себя этап, на котором вы отображаете URL-адрес своему пользователю, и ваш пользователь переходит по нему на своем более богатом устройстве ввода. Включив параметр state в первоначальный вызов OAuth, вы можете избежать отображения второго URL-адреса.

Это работает, потому что последний шаг потока OAuth 2.0 для телевизоров и приложений с ограниченным вводом данных обычно перенаправляет вашего пользователя на страницу с надписью «Теперь вы можете вернуться на свое устройство». Включив параметр состояния, последний шаг потока теперь попытается перенаправить вас на settingsUri . Ваше приложение по-прежнему получит токен OAuth. Вы должны использовать этот токен для вызова createDevice с тем же requestId . После создания устройства с тем же идентификатором первоначальный поток OAuth успешно перенаправит вашего пользователя на правильную страницу на расширенном устройстве в приложении «Фотографии».

Помните следующие моменты:

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