Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

interfejs API Permissions na Androidzie,

Zanim aplikacja zacznie korzystać z interfejsów Home API na Androidzie, musi mieć uprawnienia dostępu do urządzeń w domu użytkownika, które w interfejsie API są określane jako struktura. Za pomocą interfejsu Permissions API użytkownik może przy użyciu swojego konta Google przyznawać aplikacjom Home APIs dostęp do urządzeń w domu.

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

Integracja interfejsu Permissions API

Zanim przejdziesz dalej, wykonaj czynności opisane w sekcji Inicjowanie domu na Androidzie. W przykładach w sekcji Uprawnienia używana jest instancja homeManager z tego kroku.

Najpierw zarejestruj ActivityResultCaller w pakiecie SDK. Oto jak to robi przykładowa aplikacja:

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

Sprawdzanie uprawnień

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 weryfikacja zwróci wartość PermissionsState NOT_GRANTED lub PERMISSIONS_STATE_UNAVAILABLE, oznacza to, że użytkownik lub aplikacja nie ma dostępu do struktury. Jeśli sprawdzenie zwróci wartość PermissionsState GRANTED, ale kolejne wywołanie funkcji structures() nie zwróci żadnych struktur, oznacza to, że użytkownik cofnął 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, aplikacja musi mieć przyznane odpowiednie 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 wcześniej skonfigurować OAuth w swojej aplikacji.

Przyznaj uprawnienia

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

Developer Console rejestracja jest wymagana, aby opublikować aplikację za pomocą interfejsów Home API. Nie jest wymagana do testowania i używania interfejsów Home API.

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

Tylko użytkownicy zarejestrowani jako testerzy w konsoli OAuth mogą przyznawać uprawnienia aplikacji. W przypadku niezweryfikowanej aplikacji obowiązuje limit 100 testerów.
Niezweryfikowana aplikacja będzie mieć dostęp do urządzeń dowolnego typu obsługiwanych przez OAuth w przypadku interfejsów Home API (lista typów urządzeń w Developer Console). Wszystkie urządzenia w strukturze zostaną przyznane.

Jeśli aplikacja jest zarejestrowana w Developer Console i została zatwierdzona do uzyskiwania dostępu do co najmniej 1 typu urządzenia, a weryfikacja marki została przeprowadzona w przypadku OAuth, będzie ona w stanie zweryfikowana. Ten stan jest wymagany do wprowadzenia aplikacji na rynek:

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

Po skonfigurowaniu OAuth wywołanie aplikacji do requestPermissions() spowoduje wyświetlenie tych okien dialogowych:

Użytkownik zostanie poproszony o wybranie konta Google, którego chce używać.
Użytkownik zostanie poproszony o wybranie struktury, do której aplikacja ma mieć dostęp.
1. W przypadku niezweryfikowanej aplikacji są dostępne wszystkie typy urządzeń obsługiwane przez interfejsy Home API.
2. W przypadku zweryfikowanej aplikacji użytkownik może przyznać uprawnienia tylko typom urządzeń, które zostały zatwierdzone w Developer Console.
3. W przypadku typów urządzeń, 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.

Zgoda OAuth – wybór konta — **Ilustracja 1.** Przykład procesu zgody OAuth

Zgoda OAuth – łączenie urządzeń 01 — **Ilustracja 1.** Przykład procesu zgody OAuth

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ń w przypadku 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 jego działania.

Zmień uprawnienia

Aby przyznać uprawnienia dostępu do urządzeń w innej strukturze, można uruchomić selektor kont, który umożliwi użytkownikowi wybranie konta Google i struktury, na którą chce się przełączyć. Podczas tego procesu użytkownikowi ponownie wyświetli się ekran zgody, nawet jeśli wcześniej wyraził zgodę.

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

homeManager.requestPermissions(forceLaunch=true)

Zmienianie uprawnień za pomocą wskazówek dotyczących struktury

Wskazówki dotyczące struktury umożliwiają aplikacji wstępne wybranie konkretnej struktury lub ograniczenie listy dostępnych struktur podczas wysyłania żądania przyrostowej zmiany uprawnień użytkownika 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.

Wskazówki dotyczące struktury są zarządzane za pomocą klasy danych ConsentScreenOptions. Klasa ConsentScreenOptions akceptuje te parametry konfiguracji:

structureId – identyfikator konkretnej struktury, która ma być wstępnie wybrana w oknie uprawnień. Możesz go uzyskać, sprawdzając właściwości struktury, która jest aktualizowana.
allowedStructureIds – lista identyfikatorów struktury. Jeśli zostanie podana, okno uprawnień będzie filtrować dostępne struktury, aby wyświetlać tylko te z tej listy. W większości przypadków możesz pozostawić to pole bez zmian, chyba że chcesz mieć pewność, że użytkownik pozostanie na liście struktur, do których ma już dostęp.
allowStructureChange – określa, czy użytkownik może zmienić wstępnie wybraną strukturę. Ustaw tę wartość na true, jeśli w większości przypadków określono co najmniej jedną z właściwości allowedStructureIds i structureId, aby zapewnić użytkownikowi naturalne zachowanie.

Przekaż ten obiekt jako parametr opcjonalny w wywołaniu requestPermissions(), ustawiając flagę forceLaunch 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 pod kątem struktury podanej w obiekcie ConsentScreenOptions.

Zezwalaj użytkownikowi na przełączanie struktur za pomocą podpowiedzi dotyczących 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:

Na stronie Moje konto Google > Dane i prywatność > Aplikacje i usługi innych firm. Spowoduje to unieważnienie 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 platformach (telefonach) i strukturach.

Użytkownik może zostać przekierowany za pomocą precyzyjnego linku na podstronę Aplikacje i usługi innych firm, korzystając z tego schematu URI adresu URL:
```
https://myaccount.google.com/connections/link?project_number=Cloud project_number
```
Na stronie GHA > Ustawienia > Połączone aplikacje. Kliknięcie 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ż na niej zmienić typy urządzeń lub konkretne urządzenia wrażliwe, do których aplikacja ma dostęp.

W ekosystemie Google Home użytkownicy mogą przyznawać uprawnienia do wszystkich urządzeń danego typu jednocześnie. W przypadku urządzeń wrażliwych lub objętych ograniczeniami, takich jak zamki, kamery czy dzwonki do drzwi, użytkownicy muszą przyznawać uprawnienia indywidualnie.

Aby sprawdzić, czy użytkownik przyznał uprawnienia dostępu do urządzenia typu wrażliwego lub o ograniczonym dostępie, użyj funkcji na poziomie struktury: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
            }
        }
    }
}

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 znajdziesz opis tego, jak w takich przypadkach są egzekwowane uprawnienia.

Automatyzacja	Cechy	Wymuszanie uprawnień
O 22:00 przesyłaj komunikat „Czas na sen” na głośnik w sypialni.	`AssistantBroadcastTrait` na urządzeniu.	Tworzenie automatyzacji: Urządzenie do transmisji musi być urządzeniem z Asystentem. Aplikacja i użytkownik muszą mieć dostęp do urządzenia, na którym odbywa się transmisja. Wykonanie automatyzacji: Aplikacja i użytkownik muszą mieć dostęp do urządzenia, na którym odbywa się transmisja.
O 22:00 przesyłaj komunikat „Czas spać” na wszystkie urządzenia	`AssistantBroadcastTrait` na strukturę.	Tworzenie automatyzacji: W strukturze musi być co najmniej 1 urządzenie z Asystentem, do którego aplikacja i użytkownik mają dostęp. Aplikacja i użytkownik muszą mieć dostęp do struktury. Wykonanie automatyzacji: Aplikacja i użytkownik muszą mieć dostęp do struktury.
O 22:00 „włącz muzykę”	`AssistantFulfillmentTrait.OkGoogleCommand`	Tworzenie automatyzacji: Aplikacja i użytkownik muszą mieć dostęp do urządzeń, do których automatyzacja wysyła polecenia. Wykonanie automatyzacji: Aplikacja i użytkownik muszą mieć dostęp do urządzeń, do których automatyzacja wysyła polecenia.
Gdy ktoś powie „włącz jakąś muzykę”	`VoiceStarterTrait.OkGoogleEvent`	Tworzenie automatyzacji: Aplikacja i użytkownik muszą mieć dostęp do struktury. Automatyzacja nie wymaga urządzenia z Asystentem, aby przejść weryfikację lub działać, ponieważ każdy użytkownik mający dostęp do struktury może używać telefonu (z tym samym kontem Google), aby korzystać z Asystenta i wywoływać VoiceStarter. Wykonanie automatyzacji: Aplikacja nie wymaga uprawnień dostępu do urządzenia, które uruchamia automatyzację. Aplikacja i użytkownik muszą mieć uprawnienia dostępu do urządzenia, na którym wykonywana jest czynność.

Wskazówki, jeśli użytkownik cofnie pełne uprawnienia

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

Przy każdym uruchomieniu aplikacji sprawdzaj, czy uprawnienia nadal obowiązują. Jeśli zostały one wycofane, upewnij się, że wszystkie poprzednie dane, w tym dane zapisane w pamięci podręcznej aplikacji, zostały usunięte.

Wstecz

3. Initialize the home

Dalej

Home APIs for Android Overview