API разрешений

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

Home API использует OAuth 2.0 для предоставления доступа к устройствам в структуре. OAuth позволяет пользователю предоставлять разрешение приложению или службе без необходимости раскрывать свои учетные данные для входа. С помощью Permissions API пользователь может, используя свою учетную запись Google, предоставить приложениям Home API доступ к устройствам в своем доме.

Использование Permissions API включает в себя ряд шагов в вашем приложении, Google Cloud и Google Home Developer Console :

1. Настройте OAuth в Google Cloud
   1. Подпишите приложение
   2. Настройте экран согласия OAuth
   3. Зарегистрируйте приложение и создайте учетные данные
2. Интегрируйте API разрешений
   1. Проверьте разрешения
   2. Запросить разрешения
3. Предоставить разрешения
   1. Изменение разрешений
   2. Отозвать разрешения

Настройте OAuth в Google Cloud

Если у вас уже есть проверенный клиент OAuth, вы можете использовать его, не настраивая новый. Дополнительную информацию см. в разделе «Если у вас есть существующий клиент OAuth» .

Подпишите приложение

1. Создайте ключ OAuth, запустив приложение в Android Studio . Когда вы запускаете или отлаживаете приложение в Android Studio , оно автоматически генерирует ключ OAuth, предназначенный для разработки и отладки. См . Android Studio: подпишите отладочную сборку для получения полного объяснения.

   Подключите мобильное устройство к локальному компьютеру. Android Studio перечислит подключенные устройства по номеру модели. Выберите свое устройство из списка, затем нажмите «Запустить проект» . В результате будет создан и установлен пример приложения на ваше мобильное устройство.

   Более подробные инструкции см. в разделе «Запуск приложений на аппаратном устройстве» на сайте разработчиков Android.

   Теперь остановите работающее приложение.

2. Получите отпечаток SHA-1 сертификата OAuth, следуя инструкциям, подробно описанным в разделе «Настройка OAuth 2.0 / Собственные приложения / Android» на справочном сайте Google Cloud Console.

Настройте экран согласия OAuth

1. В консоли Google Cloud перейдите на панель выбора проектов и выберите проект, который вы хотите использовать для создания учетных данных OAuth.
2. Перейдите на страницу API и службы и нажмите «Учетные данные» в меню навигации.

3. Если вы еще не настроили экран согласия для этого проекта Google Cloud, появится кнопка «Настроить экран согласия» . В этом случае настройте экран согласия, используя следующую процедуру. В противном случае перейдите к следующему разделу.

   1. Нажмите «Настроить экран согласия» . Откроется страница экрана согласия OAuth .
   2. В зависимости от варианта использования выберите «Внутренний» или «Внешний» , а затем нажмите «Создать» . Откроется панель экрана согласия OAuth .
   3. Введите информацию на странице информации о приложении в соответствии с инструкциями на экране, а затем нажмите «Сохранить и продолжить» . Откроется панель «Области» .
   4. Вам не нужно добавлять какие-либо области, поэтому нажмите «Сохранить и продолжить» . Откроется панель Тестовые пользователи .
   5. Если вы хотите добавить пользователей для проверки доступа к вашему приложению, нажмите «Добавить пользователей» . Откроется панель Добавить пользователей . Тестовые пользователи имеют право предоставлять разрешения в вашем приложении.
   6. В пустом поле добавьте один или несколько адресов электронной почты учетной записи Google, а затем нажмите «Добавить» .
   7. Нажмите «Сохранить и продолжить» . Откроется панель «Сводка» .
   8. Просмотрите информацию на экране согласия OAuth, а затем нажмите « Вернуться на панель управления» .

Подробную информацию см. в разделе «Настройка экрана согласия OAuth» на справочном сайте Google Cloud Console.

Зарегистрируйте приложение и создайте учетные данные

Чтобы зарегистрировать приложение для OAuth 2.0 и создать учетные данные OAuth, следуйте инструкциям, приведенным в разделе «Настройка OAuth 2.0» . Вам нужно будет указать тип приложения: нативное/приложение для Android .

Добавьте отпечаток SHA-1, полученный при подписании приложения , в клиент OAuth, настроенный на консоли Google Cloud, следуя инструкциям в разделе «Настройка OAuth 2.0/родных приложений» на справочном сайте Google Cloud Console.

Подключив мобильное устройство к локальному компьютеру, выберите свое устройство из списка, затем снова нажмите «Запустить проект», чтобы запустить его. Более подробные инструкции см. в разделе «Запуск приложений на аппаратном устройстве» на сайте разработчиков Android.

Интегрируйте API разрешений

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

Сначала зарегистрируйте ActivityResultCaller с помощью SDK. Например, вот как это обрабатывает пример приложения:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

Проверьте разрешения

Прежде чем запрашивать разрешения, мы рекомендуем вам проверить, предоставил ли уже пользователь приложения свое согласие. Для этого вызовите метод hasPermissions() экземпляра Home, чтобы получить Flow значений PermissionsState :

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Если проверка возвращает PermissionsState NOT_GRANTED или PERMISSIONS_STATE_UNAVAILABLE , вам потребуется запросить разрешения. Если проверка возвращает PermissionsState GRANTED , но последующий вызов structures() не возвращает никаких структур, значит, пользователь отменил доступ к приложению через страницу настроек Google Home app (GHA) , и вам следует запросить разрешения. В противном случае у пользователя уже должен быть доступ.

Запросить разрешения

Разрешение должно быть предоставлено вашему приложению для доступа к структурам и устройствам внутри данной структуры.

Если пользователь еще не предоставил разрешения, используйте метод requestPermissions() экземпляра Home, чтобы запустить пользовательский интерфейс разрешений и обработать результат:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

Чтобы пользовательский интерфейс разрешений запускался правильно, вы уже должны настроить OAuth для своего приложения.

Предоставить разрешения

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

Регистрация Developer Console необходима для публикации приложения с использованием Home API. Тестировать и использовать Home API не требуется. Чтобы получить доступ к функции регистрации консоли, обратитесь к своему Technical Account Manager (TAM) .

Если приложение не зарегистрировано в Developer Console , оно будет в непроверенном состоянии. Это рекомендуется для тестирования использования Home API:

• Только пользователи, зарегистрированные в качестве тестовых пользователей в консоли OAuth, могут предоставлять разрешения для приложения. Для непроверенного приложения существует ограничение в 100 тестовых пользователей.

• Непроверенное приложение будет иметь доступ к устройствам любых типов, которые поддерживаются OAuth для Home API (список типов устройств в Developer Console ). Все устройства в структуре будут предоставлены.

Если приложение зарегистрировано в Developer Console и было одобрено для доступа к одному или нескольким типам устройств, а проверка бренда для OAuth завершена , оно будет в проверенном состоянии. Это состояние необходимо для запуска приложения в производство:

• Ограничения на тестовых пользователей больше не применяются. Любой пользователь может предоставить разрешение приложению.
• Пользователь может предоставить разрешения только тем типам устройств, которые были одобрены в Developer Console .

Теперь, когда OAuth настроен, вызов приложения requestPermissions() запускает следующие диалоговые окна:

1. Пользователю предлагается выбрать учетную запись Google, которую он хочет использовать.
2. Пользователю предлагается выбрать структуру, к которой он хочет предоставить приложению доступ.
   1. Непроверенному приложению доступны все типы устройств, поддерживаемые Home API.
   2. Для проверенного приложения пользователь может предоставить разрешения только тем типам устройств, которые были одобрены в Developer Console .
   3. Для конфиденциальных типов устройств, к которым у приложения есть доступ, пользователь может ограничить доступ для каждого устройства. Например, если у пользователя есть три блокировки, он может предоставить доступ только к одной из этих блокировок.

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

Изменение разрешений

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

Это можно сделать, снова вызвав requestPermissions() с флагом forceLaunch , установленным в true :

homeManager.requestPermissions(forceLaunch=true)

Отозвать разрешения

Пользователи могут отозвать ранее предоставленный доступ:

1. На странице Google MyAccounts > Данные и конфиденциальность > Сторонние приложения и службы . Это приведет к отзыву токена OAuth, который был выдан при предоставлении первоначального согласия, и аннулирует доступ к любому экземпляру приложения, которое пользователь использовал на всех поверхностях (телефонах) и в структурах.

2. Через страницу GHA > Настройки > Связанные приложения . Нажав на settings в GHA вы попадете на страницу настроек . Оттуда щелкните плитку «Связанные приложения» , которая приведет вас на страницу, похожую на экран согласия. На этой странице пользователь может удалить доступ к приложению. Пользователь может использовать эту же страницу, чтобы изменить типы устройств или конкретные чувствительные устройства, доступные приложению.

3. Через страницу связанных приложений прямо в Интернете.

Если у вас есть существующий клиент OAuth

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

Регистрация Developer Console не требуется для тестирования и использования Home API. Однако для публикации приложения вам все равно потребуется одобренная регистрация Developer Console , даже если у вас есть проверенный клиент OAuth из другой интеграции.

Применимы следующие соображения:

• При использовании существующего клиента OAuth существует ограничение в 100 пользователей. Информацию о добавлении тестовых пользователей см. в разделе Настройка экрана согласия OAuth . Независимо от проверки OAuth, Home API устанавливает ограничение в 100 пользователей, которые могут предоставлять разрешения вашему приложению. Это ограничение снимается после завершения регистрации в Developer Console .

• Регистрация Developer Console следует отправить на утверждение, когда вы будете готовы ограничить предоставление разрешений типам устройств через OAuth при подготовке к обновлению вашего приложения с помощью Home API.

Для приложений Google Cloud , которые все еще ожидают проверки OAuth, пользователи не могут завершить процесс OAuth до завершения проверки. Попытки предоставить разрешения завершатся ошибкой со следующей ошибкой:

Access blocked: <Project Name> has not completed the Google verification process.

Ок, разрешения Google

Команда okGoogle является командой уровня структуры и может использоваться для автоматизации любого устройства в структуре. Однако приложение Home API может не иметь доступа ко всем устройствам. В следующей таблице описано, как в таких случаях применяются разрешения.