API разрешений

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

Интегрируйте 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 для своего приложения.

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

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

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

Если приложение не зарегистрировано в 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. Через страницу связанных приложений прямо в Интернете.

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

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