interfejs API Permissions na Androidzie,

Zanim aplikacja będzie mogła korzystać z interfejsów API Google Home na Androida, musi mieć uprawnienia dostępu do urządzeń w domu użytkownika, które w interfejsie API są określane jako struktura. Dzięki interfejsowi Permissions API użytkownik może za pomocą swojego konta Google przyznać aplikacjom korzystającym z interfejsów Home API dostęp do urządzeń w domu.

Proces przyznawania uprawnień umożliwia użytkownikowi utworzenie domu i przypisanie do niego adresu, jeśli nie został on jeszcze skonfigurowany, bez konieczności korzystania z aplikacji Google Home app (GHA).

Integracja interfejsu Permissions API

Zanim przejdziesz dalej, upewnij się, że wykonano czynności opisane w artykule Inicjowanie domu na Androidzie. We wszystkich przykładach uprawnień używamy instancji homeManager z tego kroku.

Najpierw zarejestruj ActivityResultCaller za pomocą pakietu SDK. Na przykład w przykładowej aplikacji jest to obsługiwane w ten sposób:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

Sprawdzanie uprawnień

Przed poproszeniem o uprawnienia zalecamy sprawdzenie, czy użytkownik aplikacji wyraził już zgodę na dostęp do struktury. Aby to zrobić, wywołaj metodę hasPermissions() instancji Home, aby uzyskać Flow wartości 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())
    }
}

Jeśli kontrola zwróci PermissionsState o wartości NOT_GRANTED lub PERMISSIONS_STATE_UNAVAILABLE, oznacza to, że użytkownik lub aplikacja nie ma dostępu do struktury. Jeśli sprawdzenie zwraca PermissionsState o wartości GRANTED, ale kolejne wywołanie structures() nie zwraca żadnych struktur, oznacza to, że użytkownik unieważnił dostęp do aplikacji na stronie ustawień GHA lub nie ma wymaganego dostępu.

Wyślij prośbę o uprawnienia

Aby uzyskać dostęp do domów i urządzeń w danym domu, musisz przyznać aplikacji uprawnienia.

Jeśli użytkownik nie przyznał jeszcze uprawnień, użyj metody requestPermissions() instancji Home, aby uruchomić interfejs uprawnień i przetworzyć wynik:

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}")
      }
    }
  }
}

Aby interfejs uprawnień uruchamiał się prawidłowo, musisz mieć już skonfigurowany protokół OAuth w aplikacji.

Interfejs zgody na uprawnienia jest renderowany w języku skonfigurowanym za pomocą HomeClient.setLocale() lub domyślnie w języku aplikacji lub urządzenia, jeśli nie jest ustawiony. Aby wyświetlić ekran zgody w określonym języku, wywołaj setLocale() w instancji HomeClient przed wywołaniem requestPermissions(). Więcej informacji znajdziesz w artykule o konfigurowaniu języka aplikacji.

Przyznaj uprawnienia

Teraz możesz uruchomić aplikację i poprosić użytkownika o przyznanie uprawnień. Typy użytkowników, którzy mogą przyznawać uprawnienia, oraz typy urządzeń, na których można przyznawać uprawnienia, różnią się w zależności od tego, czy aplikacja jest zarejestrowana w Google Home Developer Console.

Aby opublikować aplikację korzystającą z interfejsów API Google Home, musisz zarejestrować się w usłudze Developer Console. Nie jest to wymagane do testowania i używania interfejsów API Google Home.

Jeśli aplikacja nie jest zarejestrowana w Developer Console, będzie miała stan niezweryfikowana. Zalecamy to rozwiązanie do testowania interfejsów Home API:

• Tylko użytkownicy zarejestrowani jako użytkownicy testowi w konsoli OAuth mogą przyznawać uprawnienia aplikacji. W przypadku niezweryfikowanej aplikacji obowiązuje limit 100 użytkowników testowych.

• Niezweryfikowana aplikacja będzie miała dostęp do urządzeń dowolnego typu obsługiwanych przez protokół OAuth w przypadku interfejsów Home API (lista typów urządzeń w Developer Console). Przyznany zostanie dostęp do wszystkich urządzeń w domu.

Jeśli aplikacja jest zarejestrowana w Developer Console i ma zatwierdzony dostęp do co najmniej 1 typu urządzenia, a weryfikacja marki została zakończona w przypadku protokołu OAuth, będzie miała stan zweryfikowana. Ten stan jest wymagany do opublikowania aplikacji w wersji produkcyjnej:

• Limity dotyczące użytkowników testowych nie będą już obowiązywać. Każdy użytkownik może przyznać uprawnienia aplikacji.
• Użytkownik może przyznać uprawnienia tylko do typów urządzeń, które zostały zatwierdzone w Developer Console.

Po skonfigurowaniu protokołu OAuth wywołanie requestPermissions() przez aplikację powoduje wyświetlenie tych okien:

1. Użytkownik zostanie poproszony o wybranie konta Google, którego chce użyć.
2. Użytkownik zostanie poproszony o wybranie domu, do którego chce przyznać aplikacji dostęp.
   1. W przypadku niezweryfikowanej aplikacji dostępne są wszystkie typy urządzeń obsługiwane przez interfejsy API Google Home.
   2. W przypadku zweryfikowanej aplikacji użytkownik może przyznać uprawnienia tylko do typów urządzeń, które zostały zatwierdzone w Developer Console.
   3. W przypadku typów urządzeń, do których aplikacja ma dostęp, użytkownik może ograniczyć dostęp na poziomie urządzenia. Jeśli na przykład użytkownik ma 3 zamki, może przyznać dostęp tylko do jednego z nich.

Po przyznaniu uprawnień aplikacja może używać interfejsów API Google Home do odczytywania stanu urządzeń w domu i sterowania nimi. Jeśli użytkownik nie przyzna aplikacji uprawnień do określonego typu urządzenia lub urządzenia wrażliwego, aplikacja nie będzie mogła używać interfejsów API Google Home do uzyskiwania dostępu do tego urządzenia, sterowania nim ani automatyzowania jego działania.

Zmień uprawnienia

Aby przyznać uprawnienia dostępu do urządzeń w innej strukturze, można uruchomić selektor kont, który pozwoli użytkownikowi wybrać konto Google i strukturę, na którą chce się przełączyć. Podczas tego procesu użytkownikowi ponownie wyświetli się ekran zgody, nawet jeśli zgoda została już wcześniej udzielona.

Możesz to zrobić, ponownie wywołując requestPermissions() z parametrem forcePermissionFlow ustawionym na ForcePermissionFlow.FORCE_LAUNCH:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Zmienianie uprawnień za pomocą sugerowania obiektu

Sugerowanie obiektu umożliwia aplikacji wstępne wybranie konkretnego obiektu lub ograniczenie listy dostępnych obiektów podczas żądania przyrostowej zmiany uprawnień użytkownika do interfejsów API Google Home. Dzięki przekazaniu parametrów domu do żądania autoryzacji okno uprawnień automatycznie skupi się na wybranym domu, co zmniejszy liczbę problemów użytkownika i zapobiegnie błędom konfiguracji.

Sugerowaniem obiektu zarządza się za pomocą klasy danych ConsentScreenOptions. Klasa ConsentScreenOptions akceptuje te parametry konfiguracji:

• structureId – identyfikator konkretnego domu, który ma być wstępnie wybrany w oknie uprawnień. Możesz go uzyskać, sprawdzając właściwości domu, który jest aktualizowany.
• allowedStructureIds – lista identyfikatorów struktur. Jeśli zostanie podana, okno uprawnień będzie filtrować dostępne struktury, aby wyświetlać tylko te, które znajdują się na tej liście. W większości przypadków nie trzeba tego określać, chyba że chcesz mieć pewność, że użytkownik pozostanie na liście domów, do których ma już przyznany dostęp.
• allowStructureChange – określa, czy użytkownik może zmienić wstępnie wybraną strukturę. Jeśli w większości przypadków określono co najmniej jedną z właściwości allowedStructureIds i structureId, ustaw wartość true, aby zapewnić użytkownikowi naturalne działanie.

Przekaż ten obiekt jako opcjonalny parametr w wywołaniu requestPermissions(), ustawiając forcePermissionFlow na 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)

Użytkownik zobaczy ekran zgody, który został już przefiltrowany pod kątem struktury określonej w obiekcie ConsentScreenOptions.

Zezwalanie użytkownikowi na przełączanie domów za pomocą sugerowania obiektu

Jeśli użytkownik ma w aplikacji kilka struktur i chcesz wstępnie wybrać jedną z nich, ale nadal umożliwiać mu przełączanie się między dostępnymi strukturami, włącz zmiany struktury za pomocą flagi allowStructureChange i podaj listę struktur w parametrze allowedStructureIds:

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

Unieważnianie uprawnień

Użytkownicy mogą cofnąć wcześniej przyznany dostęp:

1. W ustawieniach konta Google > Dane i prywatność > Aplikacje i usługi innych firm. Spowoduje to unieważnienie tokena OAuth, który został wydany po udzieleniu początkowej zgody, oraz odebranie dostępu do wszystkich instancji aplikacji, z których użytkownik korzystał na wszystkich platformach (telefonach) i w strukturach.

   Użytkownik może zostać przekierowany za pomocą precyzyjnego linku do podstrony Aplikacje i usługi innych firm przy użyciu tego schematu adresu URL:

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

2. Na stronie GHA > Ustawienia > Połączone aplikacje. Kliknięcie settings w GHA spowoduje przejście na stronę Ustawienia. Następnie kliknij kafelek Połączone aplikacje, który przeniesie Cię na stronę podobną do ekranu zgody. Na tej stronie użytkownik może usunąć dostęp do aplikacji. Może też zmienić typy urządzeń lub konkretne urządzenia wrażliwe, do których aplikacja ma dostęp.

Usuwanie i eksportowanie danych użytkownika

Platforma automatycznie zarządza usuwaniem danych backendu, gdy użytkownik usunie swoje konto Google lub opuści dom:

• Jeśli usunięty użytkownik jest jedynym właścicielem domu, platforma usunie dom i powiązane z nim urządzenia.
• Jeśli w domu współdzielonym pozostaną inni właściciele, dom i udostępnione urządzenia będą nadal dostępne dla pozostałych domowników. Platforma usunie członkostwo użytkownika, który opuścił dom, i odłączy wszystkie urządzenia innych firm (Cloud-to-cloud) połączone wyłącznie za pomocą danych logowania tego użytkownika.
• Usunięcie konta powoduje natychmiastowe i trwałe usunięcie danych domu i uprawnień aplikacji użytkownika. Nawet jeśli użytkownik później odzyska swoje konto Google, jego domy i uprawnienia nie zostaną przywrócone.

Interfejsy API Google Home nie udostępniają punktów końcowych do eksportowania ani usuwania danych na koncie Google użytkownika. Użytkowników, którzy mają konto Google, skieruj do Google Takeout, aby wyeksportowali swoje dane z Google Home, oraz do ustawień konta Google, aby usunęli konto.

Wyświetlanie typów urządzeń, do których użytkownik przyznał uprawnienia

W ekosystemie Google Home w przypadku większości typów urządzeń użytkownicy mogą przyznać uprawnienia wszystkim urządzeniom danego typu jednocześnie. W przypadku urządzeń poufnych lub z ograniczonym dostępem, takich jak zamki, kamery czy dzwonki, użytkownicy muszą przyznać uprawnienia do każdego z nich osobno.

Aby sprawdzić, czy użytkownik przyznał uprawnienia dostępu do urządzenia typu poufnego lub zastrzeżonego, użyj funkcji consentedDeviceTypes() na poziomie struktury:

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
            }
        }
    }
}

Uprawnienia Ok Google

Polecenie okGoogle jest poleceniem na poziomie urządzenia i może służyć do automatyzacji dowolnego urządzenia w domu. Aplikacja korzystająca z Home APIs może jednak nie mieć dostępu do wszystkich urządzeń. W tabeli poniżej opisano, jak w takich przypadkach są egzekwowane uprawnienia.

Wskazówki dotyczące sytuacji, gdy użytkownik cofnie pełne uprawnienia

Jeśli użytkownik cofnie pełne uprawnienia, wszystkie istniejące automatyzacje przestaną działać. Jeśli użytkownik cofnie dostęp do określonych urządzeń, elementy inicjujące, warunki i działania powiązane z tymi urządzeniami przestaną działać.

Przy każdym uruchomieniu aplikacji sprawdź, czy uprawnienia są nadal aktywne. Jeśli zostały unieważnione, upewnij się, że wszystkie poprzednie dane zostały usunięte, w tym dane zapisane w pamięci podręcznej aplikacji.

Gdy dostęp do domu zostanie cofnięty, do backendu w chmurze zostanie dostarczone zdarzenie StructureAccessRevokedEvent. Informacje o całym procesie wycofywania uprawnień do domu w aplikacji partnera w chmurze i na urządzeniach mobilnych znajdziesz w artykule Uprawnienia do domu.