Interfejs Permissions API

Zanim aplikacja będzie mogła korzystać z interfejsów Home API, 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 Home API dostęp do urządzeń w domu.

Integracja interfejsu Permissions API

Zanim przejdziesz dalej, wykonaj instrukcje w sekcji Inicjowanie domu. Przykład homeManager z tego kroku jest używany we wszystkich przykładach uprawnień.

Najpierw zarejestruj pakiet ActivityResultCaller w pakiecie SDK. Przykładowa aplikacja obsługuje to w ten sposób:

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

Sprawdzanie uprawnień

Zanim poprosisz o przyznanie uprawnień, sprawdź, czy użytkownik aplikacji nie wyraził już zgody. Aby to zrobić, wywołaj metodę hasPermissions() instancji Home, aby uzyskać tablicę Flow wartości PermissionsState:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      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")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

Jeśli sprawdzenie zwróci wartość PermissionsState NOT_GRANTED lub PERMISSIONS_STATE_UNAVAILABLE, poproś o przyznanie uprawnień. Jeśli sprawdzenie zwróci wartość PermissionsState z GRANTED, ale kolejny wywołanie funkcji structures() nie zwróci żadnych struktur, oznacza to, że użytkownik cofną dostęp do aplikacji na stronie ustawień Google Home app (GHA). W takim przypadku należy poprosić o uprawnienia. W przeciwnym razie użytkownik powinien już mieć dostęp.

Prośba o uprawnienia

Aby uzyskać dostęp do struktur i urządzeń w danej strukturze, aplikacja musi mieć odpowiednie uprawnienia.

Jeśli użytkownik nie przyznał jeszcze uprawnień, użyj metody requestPermissions() w interfejsie Głównego, aby otworzyć interfejs użytkownika dotyczący 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 już skonfigurować OAuth w swojej aplikacji.

Przyznaj uprawnienia

Aplikacja powinna się teraz uruchomić, a użytkownik powinien mieć uprawnienia. Typy użytkowników, którzy mogą przyznać uprawnienia, oraz typy urządzeń, na których można przyznać uprawnienia, różnią się w zależności od tego, czy aplikacja została zarejestrowana w Google Home Developer Console.

Aby opublikować aplikację korzystającą z interfejsów Home API, musisz zarejestrować usługę Developer Console. Nie musisz testować interfejsów API Home ani z nich korzystać.

Jeśli aplikacja nie jest zarejestrowana w Developer Console, jest w stanie niezweryfikowana. Zalecamy to w przypadku testowania korzystania z interfejsów API Home:

• Tylko użytkownicy zarejestrowani jako użytkownicy testowi w konsoli OAuth mogą przyznawać uprawnienia aplikacji. W przypadku aplikacji, która nie została zweryfikowana, można mieć maksymalnie 100 użytkowników testowych.

• Niezweryfikowana aplikacja będzie mieć dostęp do urządzeń dowolnego typu obsługiwanego przez OAuth w interfejsach Home API (lista typów urządzeń w Developer Console). Dostęp będzie przyznany wszystkim urządzeniom w strukturze.

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

• 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 do typów urządzeń, które zostały zatwierdzone w Developer Console.

Gdy już skonfigurujesz OAuth, wywołanie przez aplikację interfejsu requestPermissions() spowoduje wyświetlenie tych dialogów:

1. Użytkownik jest proszony o wybranie konta Google, którego chce użyć.
2. Użytkownik jest proszony o wybranie struktury, do której chce przyznać aplikacji dostęp.
   1. W przypadku aplikacji bez weryfikacji wszystkie typy urządzeń obsługiwane przez interfejsy API Home są dostępne dla aplikacji.
   2. W przypadku zweryfikowanej aplikacji użytkownik może przyznać uprawnienia tylko urządzeniom, które zostały zatwierdzone w Developer Console.
   3. W przypadku typów urządzeń z danymi wrażliwymi, do których aplikacja ma dostęp, użytkownik może ograniczyć dostęp na poziomie 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 udzieleniu uprawnień aplikacja może używać interfejsów API Home 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 korzystać z interfejsów API Home do uzyskiwania dostępu do tego urządzenia, sterowania nim ani automatyzacji jego działania.

Zmień uprawnienia

Aby przyznać uprawnienia dostępu do urządzeń w innej strukturze, można uruchomić selektor kont, aby umożliwić użytkownikowi wybranie konta Google i struktury, do której chce przejść. W trakcie tego procesu użytkownikowi ponownie wyświetli się ekran zgody, nawet jeśli zgoda została już wyrażona.

Aby to zrobić, wywołaj ponownie funkcję requestPermissions(), ustawiając flagę forceLaunch na wartość true:

homeManager.requestPermissions(forceLaunch=true)

Odwołanie uprawnień

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

1. Na stronie Moje konta Google > Dane i prywatność > Aplikacje i usługi innych firm. Spowoduje to unieważnienie tokena OAuth wystawionego podczas udzielania początkowej zgody i utratę dostępu do wszystkich wystąpień aplikacji, których użytkownik używał na wszystkich urządzeniach (telefonach) i w ramach wszystkich struktur.

2. Na stronie GHA > Ustawienia > Połączone aplikacje. Kliknięcie settings w sekcji GHA spowoduje przejście na stronę Ustawienia. Następnie kliknij kafelek Połączone aplikacje, aby przejść na stronę podobną do ekranu zgody. Na tej stronie użytkownik może usunąć dostęp do aplikacji. Może też zmienić na tej samej stronie typy urządzeń lub konkretne urządzenia z danymi poufnymi, które mają dostęp do aplikacji.

3. Na stronie Połączone aplikacje bezpośrednio w przeglądarce.

OkGoogle permissions

Polecenie okGoogle jest poleceniem na poziomie struktury i może służyć do automatyzacji dowolnego urządzenia w strukturze. Aplikacja interfejsów API Home może jednak nie mieć dostępu do wszystkich urządzeń. W tabeli poniżej opisujemy, jak w takich przypadkach są egzekwowane uprawnienia.