Permissions API на устройствах Android;

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

Процесс получения разрешения позволяет пользователю создать структуру и назначить ее почтовый адрес, если он ещё не настроен, без использования Google Home app (GHA).

Интегрируйте Permissions 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() не возвращает структуры, значит пользователь либо отозвал доступ к приложению на странице настроек 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 для приложения.

Интерфейс согласия на разрешения отображается на языке, заданном с помощью HomeClient.setLocale(). Если язык не задан, используется язык приложения или устройства. Чтобы окно запроса доступа показывалось на определенном языке, вызовите setLocale() в экземпляре HomeClient, прежде чем вызывать requestPermissions(). Подробнее о том, как настроить региональные параметры приложения…

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

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

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

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

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

Для этого нужно снова вызвать requestPermissions(), задав для forcePermissionFlow значение ForcePermissionFlow.FORCE_LAUNCH:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Как изменить разрешения с помощью подсказок по выбору дома

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

Подсказки по выбору дома управляются с помощью класса данных ConsentScreenOptions. Класс ConsentScreenOptions принимает следующие параметры конфигурации:

• structureId – идентификатор дома, который будет выбран по умолчанию в диалоговом окне разрешения. Его можно узнать в свойствах дома, который вы хотите обновить.
• allowedStructureIds – список идентификаторов домов. Если указать этот параметр, в диалоговом окне разрешений будут показаны только структуры из списка. В большинстве случаев это можно не указывать, если только вы не хотите, чтобы пользователь оставался в рамках уже предоставленного списка структур.
• allowStructureChange – определяет, может ли пользователь изменить выбранную структуру. Если указан хотя бы один из параметров allowedStructureIds и structureId, задайте для этого параметра значение true, чтобы обеспечить естественное поведение для пользователя.

Передайте этот объект в качестве необязательного параметра в вызове requestPermissions(), задав для forcePermissionFlow значение ForcePermissionFlow.FORCE_LAUNCH:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

Пользователь увидит окно запроса доступа, в котором уже выбрана структура, указанная в объекте ConsentScreenOptions.

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

Если у пользователя в приложении несколько домов и вы хотите выбрать один из них по умолчанию, но при этом разрешить переключаться между ними, включите смену домов с помощью флага allowStructureChange и укажите список домов в allowedStructureIds:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

Отзыв разрешений

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

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

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

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

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

Удаление и экспорт пользовательских данных

Платформа автоматически удаляет данные, когда пользователь удаляет свой аккаунт Google или покидает дом.

• Если удаленный пользователь является единственным владельцем дома, то платформа удаляет дом и связанные с ним устройства.
• Если в доме есть другие владельцы, он и устройства в нем останутся доступны для них. Платформа удаляет ушедшего пользователя и отменяет связь со всеми сторонними устройствами Cloud-to-cloud, подключенными только через его учетные данные.
• При удалении аккаунта данные о доме и разрешения приложения удаляются немедленно и без возможности восстановления. Даже если пользователь позже восстановит свой аккаунт Google, его структуры и разрешения не будут восстановлены.

В Home API нет конечных точек для экспорта или удаления данных аккаунта Google. Пользователи с аккаунтом Google могут экспортировать данные Google Home с помощью Google Архиватора и удалить аккаунт в настройках.

Как посмотреть типы устройств, для которых пользователь предоставил разрешения

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

Чтобы определить, предоставил ли пользователь разрешение на доступ к конфиденциальному или ограниченному типу устройства, используйте функцию consentedDeviceTypes() на уровне структуры:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

Разрешения для команды "Окей, Google"

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

Что делать, если пользователь отзывает полные разрешения

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

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

Когда доступ к дому отзывается, в облачный бэкенд отправляется запрос StructureAccessRevokedEvent. Полный рабочий процесс отзыва разрешений для облака и мобильного приложения партнера описан в разделе Разрешения для структуры.