Konfigurowanie aplikacji pod kątem interfejsu Ambient API

Aby zacząć korzystać z interfejsu Ambient API, skonfiguruj projekt, włączając interfejs API w Konsoli interfejsów API Google i ustawiając identyfikator klienta OAuth 2.0. Interfejs API Ambient używa protokołu OAuth 2.0 do obsługi aplikacji na telewizory i urządzenia z ograniczoną liczbą wejść.

Aplikacja wchodzi w interakcję z interfejsem Ambient API w imieniu użytkownika tego interfejsu. Użytkownik autoryzuje te żądania interfejsu API za pomocą protokołu OAuth 2.0.

Identyfikator klienta OAuth 2.0 umożliwia użytkownikom aplikacji logowanie się, uwierzytelnianie i w ten sposób korzystanie z interfejsu Ambient API. Interfejs Ambient API nie obsługuje kont usługi. Aby korzystać z tych interfejsów API, użytkownicy muszą zalogować się na prawidłowe konto Google.

Konfiguracja aplikacji

Najpierw włącz interfejs API, a potem poproś o identyfikator klienta OAuth 2.0.

Włącz API

Aby móc korzystać z interfejsu Ambient API, musisz go włączyć w projekcie.

1. Otwórz konsolę interfejsów API Google.
2. Na pasku menu wybierz projekt lub utwórz nowy.
3. Aby otworzyć jeden z interfejsów API Google Photos, w menu nawigacyjnym kliknij Interfejsy API i usługi > Biblioteka.
4. Wyszukaj „Ambient API”. Wybierz interfejs API Ambient i kliknij Włącz.

Prośba o identyfikator klienta OAuth 2.0

Aby poprosić o identyfikator klienta OAuth i skonfigurować go w aplikacji, wykonaj te czynności. Interfejs API Ambient używa protokołu OAuth 2.0 do obsługi aplikacji na telewizory i urządzenia z ograniczoną liczbą wejść.

1. Otwórz Konsolę interfejsów API Google i wybierz swój projekt.
2. W menu kliknij Interfejsy API i usługi > Dane logowania.

3. Na stronie Dane logowania kliknij Utwórz dane logowania > Identyfikator klienta OAuth.

   Uwaga: jeśli konfigurujesz nowy projekt, możesz zobaczyć prośbę o skonfigurowanie ekranu zgody w projekcie.

4. Wybierz Typ aplikacji. W tym przykładzie typ aplikacji to TV i urządzenia z ograniczoną możliwością wpisywania.

5. Podaj nazwę klienta OAuth 2.0 i kliknij Utwórz.

6. W wyświetlonym oknie klienta OAuth skopiuj te informacje:

   • Identyfikator klienta
   • Tajny klucz klienta

Aplikacja może uzyskać dostęp do włączonych interfejsów API Google, korzystając z tych wartości.

Zanim opublikujesz aplikację publiczną, która uzyskuje dostęp do interfejsu Ambient API, musisz ją przesłać do sprawdzenia przez Google. Gdy testujesz aplikację, na ekranie będzie widoczny komunikat „Aplikacja niezweryfikowana” do czasu, aż zostanie zweryfikowana.

Po skonfigurowaniu aplikacji możesz zacząć korzystać z usługi. Możesz zapoznać się z tymi materiałami lub przeczytać więcej o uproszczonym procesie uwierzytelniania w przypadku interfejsu Ambient API.

• Tworzenie urządzeń i zarządzanie nimi
• Wyświetlanie i pobieranie elementów multimedialnych

Zmiana identyfikatora klienta

Zasoby utworzone za pomocą dowolnego interfejsu API Zdjęć Google można uzyskać lub zmodyfikować tylko za pomocą oryginalnego identyfikatora klienta użytego do ich utworzenia. Jeśli na przykład utworzysz w interfejsie API Picker interfejsu API session z określonym identyfikatorem klienta, a potem zmienisz ten identyfikator w aplikacji, aplikacja utraci dostęp do wszystkich zasobów interfejsu API utworzonych za pomocą poprzedniego identyfikatora klienta.

Uważnie zaplanuj i wybierz odpowiedni typ identyfikatora klienta dla używanego przez Ciebie interfejsu API Zdjęć. Zmień identyfikator klienta tylko wtedy, gdy jest to absolutnie konieczne, aby uniknąć problemów z dostępem.

Uproszczony proces uwierzytelniania w przypadku interfejsu Ambient API

Standardowy proces uwierzytelniania w ramach interfejsu Ambient API wymaga od użytkowników zeskanowania 2 kodów QR:

• Po pierwsze, zaloguj się na swoje konto Google (jeśli nie jesteś jeszcze zalogowany).
• Drugi, który łączy się z nowo utworzonym urządzeniem Ambient na koncie Zdjęć Google, gdzie użytkownik może wybrać elementy multimedialne do wyświetlania.

Uproszczony proces umożliwia udostępnienie użytkownikom jednego kodu QR przez przekazanie dodatkowego parametru state w początkowym wywołaniu uwierzytelniania.

Podczas żądania kodów urządzenia i użytkownika w ramach protokołu OAuth w przypadku urządzeń z ograniczonym wejściem dołącz do żądania dodatkowy parametr state. Dodaj do parametru state te informacje:

Parametry
requestId	string Wymagany. Unikalny identyfikator podany przez klienta dla tego żądania. Służy to ograniczeniu duplikacji zasobów w przypadku awarii sieci. Identyfikator musi mieć format ciągu znaków UUID (wersja 4) i spełniać te wymagania: Nie może zawierać żadnych poufnych informacji umożliwiających identyfikację użytkownika. Musi zawierać 32 znaki szesnastkowe podzielone na 5 grup oddzielonych myślnikami w postaci „xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” (lub 8-4-4-4-12).
displayName	string Opcjonalnie: Zdefiniowana przez użytkownika wyświetlana nazwa tego urządzenia. Będzie on widoczny dla użytkowników w ustawieniach aplikacji Zdjęcia Google, ale będzie można go edytować tylko za pomocą tego interfejsu API. Prawidłowe nazwy wyświetlane muszą mieć od 1 do 100 znaków (włącznie).

Przykładowy blok kodu:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Pomyślna odpowiedź będzie zawierać user_code i verification_url, które możesz wyświetlić użytkownikowi (najprawdopodobniej jako kod QR), aby mógł przejść do tej strony na innym urządzeniu. Jeśli w wywołaniu createDevice za pomocą interfejsu Ambient API podasz parametr state, możesz pominąć prezentowanie settingsUri w drugim kodzie QR, ponieważ ostatni krok w procedurze OAuth automatycznie przekieruje Cię do tej lokalizacji.

Poniżej znajdziesz bardziej szczegółowe informacje. Możesz też sprawdzić kod w naszej aplikacji przykładowej, aby zobaczyć przykład użycia parametru state w ramach OAuth na urządzeniach z ograniczonymi możliwościami wprowadzania danych za pomocą interfejsu Ambient API.

Szczegóły dotyczące uproszczonego procesu uwierzytelniania

Aby w pełni zrozumieć uproszczony przepływ OAuth w przypadku interfejsu Ambient API, warto zapoznać się z przepływem OAuth 2.0 dla aplikacji na telewizory i urządzenia z ograniczoną liczbą wejść, a także ze standardowym przepływem interfejsu Ambient API. Poniżej znajdziesz instrukcje dotyczące każdego z tych procesów.

OAuth 2.0 na potrzeby aplikacji na telewizory i urządzenia z ograniczonymi możliwościami wprowadzania danych:

1. Aplikacja wysyła żądanie do serwera autoryzacji Google, który określa zakresy, do których aplikacja będzie prosić o dostęp.
2. Serwer odpowiada, przekazując kilka informacji, które są używane w kolejnych krokach, np. kod urządzenia i kod użytkownika.
3. Wyświetlasz informacje, które użytkownik może wpisać na osobnym urządzeniu, aby autoryzować aplikację.
4. Aplikacja zaczyna wysyłać zapytania do serwera autoryzacji Google, aby sprawdzić, czy użytkownik autoryzował Twoją aplikację.
5. Użytkownik przełącza się na urządzenie z bogatszymi możliwościami wprowadzania danych, uruchamia przeglądarkę internetową, przechodzi do adresu URL wyświetlonego w kroku 3 i wpisuje kod, który również wyświetla się w kroku 3. Użytkownik może wtedy zezwolić (lub odmówić) dostępu do aplikacji.
6. Następna odpowiedź na żądanie sondowania zawiera tokeny, których aplikacja potrzebuje do autoryzacji żądań w imieniu użytkownika. Jeśli użytkownik odmówił udzielenia dostępu do aplikacji, odpowiedź nie będzie zawierać tokenów.

Przepływ danych w ramach interfejsu Ambient API:

1. Sprawdź, czy masz token OAuth. Jeśli tak, odśwież go lub poproś o nowy.
2. Po uzyskaniu tokena OAuth utwórz nowe urządzenie.
3. Wyświetl użytkownikowi settingsUri i rozpocznij odpytywanie urządzenia, aż mediaSourcesSet zwróci wartość Prawda.
4. Użytkownik przechodzi do settingsUri i wybiera zdjęcia, które chce udostępnić aplikacji.
5. Gdy mediaSourcesSet zwróci wartość „True” (Prawda), pobierz listę mediaItems.
6. Teraz możesz rozpocząć pokaz slajdów lub inną prezentację.

Oba procesy obejmują wyświetlenie użytkownikowi adresu URL, do którego przechodzi on na urządzeniu z bogatszymi funkcjami wejściowymi. Dodanie parametru state w pierwszym wywołaniu protokołu OAuth pozwala uniknąć wyświetlania drugiego adresu URL.

Ten sposób działa, ponieważ ostatni krok procesu OAuth 2.0 dla aplikacji na telewizory i urządzenia z ograniczonym wejściem zwykle przekierowuje użytkownika na stronę z komunikatem „Możesz teraz wrócić do urządzenia”. Jeśli dołączysz parametr state, ostatni krok przepływu spróbuje przekierować Cię do settingsUri. Twoja aplikacja nadal będzie otrzymywać token OAuth. Użyj tego tokena do wywołania funkcji createDevice za pomocą tego samego requestId. Po utworzeniu urządzenia z tym samym identyfikatorem początkowy przepływ OAuth przekieruje użytkownika na odpowiednią stronę w aplikacji Zdjęcia na urządzeniu z funkcjami multimedialnymi.

Pamiętaj o tych kwestiach:

• Warto jednak wyświetlać settingsUri na wypadek problemów z uwierzytelnianiem.
• Nadal możesz używać settingsUri w innych przypadkach, np. gdy użytkownik chce zaktualizować wybrane zdjęcia.