interfejs API Permissions na Androidzie,

Zanim zaczniesz korzystać z interfejsów Home API na Androidzie, musisz przyznać aplikacji 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 przy użyciu swojego konta Google przyznać aplikacjom korzystającym z interfejsów Home API dostęp do urządzeń w swoim domu.

Proces przyznawania uprawnień umożliwia użytkownikowi utworzenie struktury, jeśli nie została ona jeszcze skonfigurowana , bez konieczności korzystania z Google Home app (GHA).

Integracja interfejsu Permissions API

Zanim przejdziesz dalej, upewnij się, że masz zainicjowany dom na Androidzie. Wszystkie przykłady uprawnień używają instancji homeManager z tego kroku.

Najpierw zarejestruj ActivityResultCaller w pakiecie SDK. Oto jak to wygląda w aplikacji przykładowej:

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

Sprawdzanie uprawnień

Zanim poprosisz o uprawnienia, zalecamy sprawdzenie, czy użytkownik aplikacji przyznał 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 sprawdzenie zwróci wartość PermissionsState równą NOT_GRANTED lub PERMISSIONS_STATE_UNAVAILABLE, oznacza to, że użytkownik lub aplikacja nie mają dostępu do struktury. Jeśli sprawdzenie zwróci wartość PermissionsState równą GRANTED ale kolejne wywołanie structures() nie zwróci żadnych struktur, oznacza to, że użytkownik cofnął dostęp do aplikacji na stronie ustawień aplikacji GHA lub nie ma wymaganych uprawnień.

Prośba o uprawnienia

Aby uzyskać dostęp do struktur i urządzeń w danej strukturze, 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ń mógł się prawidłowo uruchomić, musisz skonfigurować OAuth dla swojej aplikacji.

Przyznawanie uprawnień

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

Developer Console rejestracja jest wymagana do opublikowania aplikacji za pomocą interfejsów Home API. Nie jest ona wymagana do testowania i używania interfejsów Home API.

Jeśli aplikacja nie jest zarejestrowana w Developer Console, będzie w stanie niezweryfikowanym. Jest to zalecane w przypadku testowania korzystania z interfejsów Home API:

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

• Aplikacja niezweryfikowana będzie mieć dostęp do urządzeń dowolnego typu obsługiwanego przez OAuth w przypadku interfejsów Home API (lista typów urządzeń w Developer Console). Uprawnienia zostaną przyznane do wszystkich urządzeń w strukturze.

Jeśli aplikacja jest zarejestrowana w Developer Console i została zatwierdzona pod kątem dostępu do co najmniej 1 typu urządzenia oraz przeszła weryfikację marki w OAuth, będzie w stanie zweryfikowanym. Ten stan jest wymagany do uruchomienia aplikacji w środowisku produkcyjnym:

• Limity użytkowników testowych nie obowiązują. Uprawnienia do aplikacji może przyznać każdy użytkownik.
• Użytkownik może przyznać uprawnienia tylko do typów urządzeń, które zostały zatwierdzone w Developer Console.

Gdy OAuth jest skonfigurowany, wywołanie requestPermissions() przez aplikację powoduje wyświetlenie tych okien:

1. Użytkownik jest proszony o wybranie konta Google, którego chce używać.
2. Użytkownik jest proszony o wybranie struktury, do której chce przyznać aplikacji dostęp.
   1. W przypadku aplikacji niezweryfikowanej aplikacja ma dostęp do wszystkich typów urządzeń obsługiwanych przez interfejsy Home API.
   2. W przypadku aplikacji zweryfikowanej 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ń wrażliwych, którymi aplikacja może zarządzać, użytkownik może ograniczyć dostęp do poszczególnych urządzeń. 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 Home API do odczytywania stanu urządzeń w strukturze 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 Home API do uzyskiwania dostępu do tego urządzenia, sterowania nim ani automatyzowania go.

Zmiana uprawnień

Aby przyznać uprawnienia dostępu do urządzeń w innej strukturze, można uruchomić selektor konta, aby użytkownik mógł wybrać konto Google i strukturę, na którą chce się przełączyć. Podczas tego procesu użytkownik ponownie zobaczy ekran zgody, nawet jeśli wcześniej wyraził zgodę.

Można to zrobić, ponownie wywołując requestPermissions() z flagą forceLaunch ustawioną na true:

homeManager.requestPermissions(forceLaunch=true)

Zmiana uprawnień z podpowiedzią dotyczącą struktury

Podpowiedź dotycząca struktury umożliwia aplikacji wstępne wybranie konkretnej struktury lub ograniczenie listy dostępnych struktur podczas wysyłania prośby o przyznanie dodatkowych uprawnień do interfejsów Home API. Przekazując parametry struktury w żądaniu autoryzacji, okno uprawnień automatycznie skupi się na wybranej strukturze, co zmniejszy trudności użytkownika i zapobiegnie błędom konfiguracji.

Podpowiedź dotycząca struktury jest zarządzana za pomocą ConsentScreenOptions klasy danych. Klasa ConsentScreenOptions akceptuje te parametry konfiguracji:

• structureId – konkretny identyfikator struktury, który ma być wstępnie wybrany w oknie uprawnień. Uzyskaj go, sprawdzając właściwości struktury struktury, która jest aktualizowana.
• allowedStructureIds – lista identyfikatorów struktur. Jeśli podasz tę listę, 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 możesz pozostawić to pole nieokreślone, chyba że chcesz mieć pewność, że użytkownik pozostanie na liście struktur, do których ma już przyznane uprawnienia.
• allowStructureChange – określa, czy użytkownik może zmienić wstępnie wybraną strukturę. W większości przypadków ustaw tę wartość na true, jeśli co najmniej 1 z parametrów allowedStructureIds i structureId jest określony, aby zapewnić naturalne zachowanie użytkownika.

Przekaż ten obiekt jako parametr opcjonalny w wywołaniu requestPermissions() z flagą forceLaunch ustawioną na true:

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(forceLaunch=true, consentOptions)

Użytkownik zobaczy ekran zgody już przefiltrowany do struktury podanej w obiekcie ConsentScreenOptions.

Zezwalanie użytkownikowi na przełączanie struktur za pomocą podpowiedzi dotyczącej struktury

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

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

Cofanie uprawnień

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

1. Na stronie Moje konto Google > Dane i prywatność > Aplikacje i usługi innych firm. Spowoduje to cofnięcie tokena OAuth, który został wydany po przyznaniu początkowej zgody, oraz cofnięcie dostępu do wszystkich instancji aplikacji, z których użytkownik korzystał na wszystkich urządzeniach (telefonach) i strukturach.

   Użytkownik może zostać przekierowany za pomocą precyzyjnego linku na podstronę Aplikacje i usługi innych firm za pomocą tego schematu URI 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.

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 do wszystkich urządzeń tego typu naraz. W przypadku typów urządzeń wrażliwych lub objętych ograniczeniami, takich jak zamki, kamery czy dzwonki do drzwi, użytkownicy muszą przyznać uprawnienia do każdego z nich osobno.

Aby sprawdzić, czy użytkownik przyznał uprawnienia dostępu do typu urządzenia wrażliwego lub objętego ograniczeniami, 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 OkGoogle

Polecenie okGoogle jest poleceniem na poziomie urządzenia i może służyć do automatyzacji dowolnego urządzenia w strukturze. Aplikacja korzystająca z interfejsów Home API 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, jeśli użytkownik cofnie wszystkie uprawnienia

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

Za każdym razem, gdy aplikacja się uruchamia, sprawdzaj, czy uprawnienia nadal obowiązują. Jeśli zostały cofnięte, usuń wszystkie poprzednie dane, w tym dane zapisane w pamięci podręcznej aplikacji.