API разрешений на Android

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

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

Прежде чем продолжить, убедитесь, что вы выполнили Инициализацию дома на Android . Экземпляр 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 для API Home (список типов устройств в Developer Console ). Всем устройствам в структуре будет предоставлен доступ.

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

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

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

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

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

Изменить разрешения

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

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

homeManager.requestPermissions(forceLaunch=true)

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

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

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

   Пользователь может быть перенаправлен с помощью глубокой ссылки на подстраницу «Сторонние приложения и сервисы» с использованием следующей схемы URL:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

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

Разрешения OkGoogle

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