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

Прежде чем использовать Home API для 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. Пользователь может ограничить доступ к отдельным устройствам, которые относятся к конфиденциальным типам и которыми управляет приложение. Например, если у пользователя три замка, он может предоставить доступ только к одному из них.
  • Запрос доступа OAuth – выбор аккаунта
  • OAuth consent - link devices 01
  • OAuth consent - link device 02
Рисунок 1. Пример процесса получения согласия OAuth

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

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

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

Автоматизация Черта характера Применение разрешений
В 22:00 воспроизвести сообщение "Пора спать" на колонке в спальне. AssistantBroadcastTrait на устройстве. Создание автоматизации:
  • Устройство, с которого отправляется оповещение, должно быть устройством с Ассистентом.
  • У приложения и пользователя должен быть доступ к устройству, на котором происходит трансляция.
Выполнение автоматизации:
  • У приложения и пользователя должен быть доступ к устройству, на котором происходит трансляция.
В 22:00 воспроизвести сообщение "Пора спать" на всех устройствах AssistantBroadcastTrait на структуру. Создание автоматизации:
  • В доме должно быть хотя бы одно устройство с Ассистентом, к которому у приложения и пользователя есть доступ.
  • У приложения и пользователя должен быть доступ к структуре.
Выполнение автоматизации
  • У приложения и пользователя должен быть доступ к структуре.
В 22:00: "Включи музыку". AssistantFulfillmentTrait.OkGoogleCommand Создание автоматизации:
  • У приложения и пользователя должен быть доступ к устройствам, которым автоматизация отправляет команды.
Выполнение автоматизации
  • У приложения и пользователя должен быть доступ к устройствам, которым автоматизация отправляет команды.
Когда кто-то говорит "Включи музыку" VoiceStarterTrait.OkGoogleEvent Создание автоматизации:
  • У приложения и пользователя должен быть доступ к структуре. Для проверки или запуска автоматизации устройство с Ассистентом не требуется, поскольку любой пользователь, у которого есть доступ к дому, может запустить VoiceStarter через Ассистента на телефоне, войдя в тот же аккаунт Google.
Выполнение автоматизации:
  • Приложению не требуется разрешение на доступ к устройству, которое запускает автоматизацию.
  • У приложения и пользователя должно быть разрешение на доступ к устройству, на котором выполняется действие.

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

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

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

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