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

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

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

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

Сначала зарегистрируйте ActivityResultCaller в SDK. Например, вот как это реализовано в Sample App:

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 .

Для публикации приложения с использованием Home API требуется регистрация Developer Console . Для тестирования и использования 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. Для конфиденциальных типов устройств, к управлению которыми у приложения есть доступ, пользователь может ограничить доступ для каждого устройства отдельно. Например, если у пользователя три замка, он может предоставить доступ только к одному из них.

После получения разрешения приложение сможет использовать 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 может иметь доступ не ко всем устройствам. В следующей таблице описано, как применяются разрешения в таких случаях.