interfejs API Permissions na Androidzie,

Zanim aplikacja zacznie korzystać z interfejsów Home API na Androida, musi mieć uprawnienia do uzyskiwania 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.

Integracja interfejsu Permissions API

Zanim przejdziesz dalej, wykonaj czynności opisane w sekcji Inicjowanie domu na Androidzie. Instancja homeManager z tego kroku jest używana we wszystkich przykładach dotyczących uprawnień.

Najpierw zarejestruj ActivityResultCaller w pakiecie SDK. Oto jak przykładowa aplikacja sobie z tym radzi:

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

Sprawdzanie uprawnień

Przed poproszeniem o uprawnienia sprawdź, czy użytkownik aplikacji wyraził już zgodę. Aby to zrobić, wywołaj metodę hasPermissions() instancji Home, aby uzyskać 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 weryfikacja zwróci wartość PermissionsState NOT_GRANTED lub PERMISSIONS_STATE_UNAVAILABLE, musisz poprosić o uprawnienia. 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ń Google Home app (GHA) i musisz poprosić go o przyznanie uprawnień. W przeciwnym razie użytkownik powinien mieć już dostęp.

Prośba 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ń został prawidłowo uruchomiony, 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.

Aby opublikować aplikację za pomocą interfejsów Home API, musisz zarejestrować Developer Console. Nie jest to wymagane 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 do aplikacji. W przypadku niezweryfikowanej aplikacji limit wynosi 100 testerów.

• Niezweryfikowana aplikacja 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). 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 miała stan 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 requestPermissions() przez aplikację spowoduje wyświetlenie tych okien dialogowych:

1. Użytkownik zostanie poproszony o wybranie konta Google, którego chce używać.
2. 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.

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 go.

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)

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 unieważnienie tokena OAuth, który został wydany po uzyskaniu początkowej zgody, oraz unieważnienie 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 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ż na niej zmienić typy urządzeń lub konkretne urządzenia wrażliwe, do których aplikacja ma dostęp.

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.