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 ->
    when (state) {
      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")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

Если проверка возвращает 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 .

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

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

• Только пользователи, зарегистрированные в консоли 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 Мой аккаунт > Данные и конфиденциальность > Сторонние приложения и сервисы . Это аннулирует токен OAuth, выданный при первоначальном предоставлении согласия, и отменит доступ ко всем экземплярам приложения, которые пользователь использовал на всех устройствах (телефонах) и платформах.

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

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

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

Разрешения OkGoogle

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

Рекомендации в случае отзыва пользователем полных прав доступа

Если пользователь отзовет полные права доступа, все существующие автоматизации перестанут работать. Кроме того, если пользователь отзовет доступ к определенным устройствам, то запуски, условия и действия, связанные с этими устройствами, перестанут работать.

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