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.

Interfejsy API Home używają OAuth 2.0 do przyznawania dostępu do urządzeń w ramach danej struktury. Protokół OAuth umożliwia użytkownikowi udzielenie uprawnień aplikacji lub usłudze bez konieczności ujawniania danych logowania. Dzięki interfejsowi Permissions API użytkownik może przy użyciu swojego konta Google przyznać aplikacjom interfejsów Home API dostęp do urządzeń w domu.

Korzystanie z interfejsu Permissions API wymaga wykonania kilku czynności w aplikacji, Google Cloud i Google Home Developer Console:

1. Konfigurowanie OAuth w Google Cloud
   1. Podpisywanie aplikacji
   2. Konfigurowanie ekranu zgody OAuth
   3. Rejestrowanie aplikacji i tworzenie danych logowania
2. Zintegruj interfejs API dotyczący uprawnień
   1. Sprawdzanie uprawnień
   2. Prośba o uprawnienia
3. Przyznawanie uprawnień
   1. Zmień uprawnienia
   2. Odwołanie uprawnień

Konfigurowanie OAuth w Google Cloud

Jeśli masz już zweryfikowanego klienta OAuth, możesz go używać bez konfigurowania nowego. Więcej informacji znajdziesz w artykule Jeśli masz już klienta OAuth.

Podpisywanie aplikacji

1. Wygeneruj klucz OAuth, uruchamiając aplikację w trybie Android Studio. Gdy uruchamiasz aplikację w Android Studio lub debugujesz ją, automatycznie generuje ona klucz OAuth przeznaczony do tworzenia i debugowania. Pełne wyjaśnienie znajdziesz w artykule Android Studio: podpisywanie wersji debugowej.

   Połącz urządzenie mobilne z komputerem lokalnym. Android Studio wyświetli listę połączonych urządzeń według numeru modelu. Wybierz urządzenie z listy, a potem kliknij Uruchom projekt. Spowoduje to wygenerowanie i zainstalowanie przykładowej aplikacji na urządzeniu mobilnym.

   Szczegółowe instrukcje znajdziesz w artykule Uruchamianie aplikacji na urządzeniu z Androidem na stronie dla deweloperów aplikacji na Androida.

   Zatrzymaj uruchomioną aplikację.

2. Aby uzyskać odcisk cyfrowy SHA-1 certyfikatu OAuth, wykonaj instrukcje podane w artykule Konfigurowanie OAuth 2.0 – aplikacje natywnych / Android w Centrum pomocy konsoli Google Cloud.

Konfigurowanie ekranu zgody OAuth

1. W konsoli Google Cloud otwórz panel wyboru projektu i wybierz projekt, którego chcesz użyć do utworzenia danych uwierzytelniających OAuth.
2. Otwórz stronę Interfejsy API i usługi, a potem w menu nawigacyjnym kliknij Dane logowania.

3. Jeśli nie masz jeszcze skonfigurowanego ekranu zgody w tym projekcie Google Cloud, pojawi się przycisk Skonfiguruj ekran zgody. W takim przypadku skonfiguruj ekran zgody, korzystając z tej procedury. W przeciwnym razie przejdź do następnej sekcji.

   1. Kliknij Skonfiguruj ekran zgody. Wyświetla się strona Ekran zgody OAuth.
   2. W zależności od przypadku użycia wybierz Wewnętrzny lub Zewnętrzny, a następnie kliknij Utwórz. Pojawi się panel Ekran zgody OAuth.
   3. Wpisz informacje na stronie z informacjami o aplikacji zgodnie z instrukcjami wyświetlanymi na ekranie, a potem kliknij Zapisz i kontynuuj. Pojawi się panel Zakresy.
   4. Nie musisz dodawać żadnych zakresów, więc kliknij Zapisz i kontynuuj. Wyświetli się panel Użytkownicy testowi.
   5. Jeśli chcesz dodać użytkowników, którzy będą testować dostęp do aplikacji, kliknij Dodaj użytkowników. Pojawi się panel Dodaj użytkowników. Użytkownicy testowi mają uprawnienia do przyznawania uprawnień w aplikacji.
   6. W pustym polu dodaj co najmniej 1 adres e-mail konta Google, a następnie kliknij Dodaj.
   7. Kliknij Zapisz i kontynuuj. Pojawi się panel Podsumowanie.
   8. Zapoznaj się z informacjami na ekranie zgody OAuth, a potem kliknij Wróć do panelu.

Więcej informacji znajdziesz w artykule Konfigurowanie ekranu zgody OAuth w Centrum pomocy konsoli Google Cloud.

Rejestrowanie aplikacji i tworzenie danych logowania

Aby zarejestrować aplikację w usłudze OAuth 2.0 i utworzyć dane logowania OAuth, wykonaj instrukcje podane w artykule Konfigurowanie OAuth 2.0. Musisz wskazać typ aplikacji, czyli natywna/aplikacja na Androida.

Dodaj odcisk cyfrowy SHA-1 uzyskany z podpisywania aplikacji do klienta OAuth skonfigurowanego w konsoli Google Cloud. Aby to zrobić, postępuj zgodnie z instrukcjami w artykule Konfigurowanie OAuth 2.0 / aplikacje natywne w Pomocy konsoli Google Cloud.

Po podłączeniu urządzenia mobilnego do komputera lokalnego wybierz je na liście, a następnie ponownie kliknij Uruchom projekt. Więcej szczegółowych informacji znajdziesz w artykule Uruchamianie aplikacji na urządzeniu z Androidem na stronie dla deweloperów aplikacji na Androida.

Integracja interfejsu Permissions API

Aby uzyskać dostęp do urządzeń w danej strukturze, użytkownicy muszą przyznać Twojej aplikacji odpowiednie uprawnienia. Najpierw upewnij się, że inicjujesz interfejsy API Google Home. W przypadku wszystkich przykładów uprawnień używana jest instancja homeManager z tego kroku.

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 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ć. Aby uzyskać dostęp do funkcji rejestracji konsoli, skontaktuj się z zespołem pomocy GoogleTechnical Account Manager (TAM).

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.

Jeśli masz już klienta OAuth

Jeśli masz już zweryfikowanego klienta OAuth dla opublikowanej aplikacji, możesz użyć tego klienta do testowania interfejsów API Home.

Aby testować interfejsy API Home i z nich korzystać, nie musisz rejestrować aplikacji Developer Console. Aby opublikować aplikację, musisz jednak mieć zatwierdzone konto Developer Console, nawet jeśli masz zweryfikowanego klienta OAuth z innej integracji.

Należy wziąć pod uwagę te kwestie:

• Jeśli używasz istniejącego klienta OAuth, obowiązuje limit 100 użytkowników. Informacje o dodawaniu użytkowników testowych znajdziesz w artykule Konfigurowanie ekranu zgody OAuth. Niezależnie od weryfikacji OAuth, interfejsy API Google Home nakładają limit 100 użytkowników, którzy mogą przyznać uprawnienia Twojej aplikacji. Ograniczenie zostanie zniesione po zakończeniu rejestracji Developer Console.

• Developer Console rejestracji należy przesłać do zatwierdzenia, gdy będziesz gotowy do ograniczenia uprawnień typu urządzenie za pomocą OAuth w ramach przygotowań do aktualizacji aplikacji za pomocą interfejsów Home API.

W przypadku aplikacji Google Cloud, które czekają na weryfikację OAuth, użytkownicy nie mogą dokończyć procesu OAuth, dopóki nie zostanie ona zakończona. Próby przyznania uprawnień nie powiedzie się i wyświetli się ten komunikat o błędzie:

Access blocked: <Project Name> has not completed the Google verification process.

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.