Korzystanie z interfejsu Ambient API

Interfejs Ambient API umożliwia aplikacji łączenie urządzeń otoczenia z kontem Zdjęć Google użytkownika i wyświetlanie wybranych przez niego zdjęć.

Przepływ Ambient API

Oto jak działa Ambient API, aby połączyć urządzenie, a następnie pobrać i wyświetlić elementy multimedialne:

  1. Sprawdź, czy urządzenie już istnieje (zalecane): przed utworzeniem nowego urządzenia zalecamy sprawdzenie, czy urządzenie dla bieżącego użytkownika już istnieje. Aplikacja powinna utrzymywać mapowanie między wewnętrznym użytkownikiem a identyfikatorem deviceId dostarczonym przez Google w przypadku wszystkich urządzeń, które użytkownik utworzy za pomocą aplikacji. Jeśli dla użytkownika zostanie znaleziony identyfikator deviceId, możesz w razie potrzeby odświeżyć jego token autoryzacji.

  2. Rozpocznij autoryzację OAuth 2.0 (i opcjonalnie utwórz urządzenie): rozpocznij proces OAuth 2.0 na potrzeby telewizorów i urządzeń z ograniczonymi możliwościami wprowadzania danych, wysyłając prośbę o kod autoryzacji.

  3. Utwórz nowe urządzenie: aplikacja tworzy urządzenie na koncie Zdjęć Google użytkownika, wywołując funkcję CreateDevice i podając prawidłowy identyfikator UUID w wersji 4.

    Po utworzeniu urządzenia interfejs API zwróci obiekt AmbientDevice zawierający przypisany przez Google identyfikator deviceId. Konieczne jest, aby Twoja aplikacja przechowywała ten deviceId i powiązywała go z użytkownikami.

  4. Wyświetl settingsUri: obiekt AmbientDevice zawiera settingsUri. Przedstaw ten URI użytkownikowi, zwykle w postaci kodu QR, który może zeskanować za pomocą urządzenia mobilnego. Ten URI przekierowuje użytkownika do aplikacji Zdjęcia Google, w której może on skonfigurować źródła multimediów (np. albumy), które chce wyświetlać na urządzeniu w trybie otoczenia.

  5. Odpytywanie mediaSourcesSet: aplikacja powinna okresowo wywoływać metodę GetDevice, podając deviceId, aby sprawdzić stan urządzenia otoczenia. Monitoruj pole mediaSourcesSet w odpowiedzi AmbientDevice. Początkowo będzie mieć wartość fałsz.

    Gdy użytkownik wybierze źródła multimediów w aplikacji Zdjęcia Google, to pole zmieni się na wartość „true”.

    Odpowiedź AmbientDevice zawiera pollingConfig z wartością pollInterval, która powinna być dla Ciebie wskazówką dotyczącą częstotliwości odpytywania.

  6. Pobieranie plików multimedialnych: gdy mediaSourcesSet zwraca wartość „true”, aplikacja może rozpocząć pobieranie plików multimedialnych wybranych przez użytkownika.

    Wywołaj metodę ListMediaItems, podając deviceId. Interfejs API zwróci obiekt ListMediaItemsResponse zawierający listę obiektów AmbientMediaItem. Każdy AmbientMediaItem zawiera szczegóły, takie jak id, createTime i obiekt MediaFile z dodatkowymi metadanymi. Element MediaFile zawiera element baseUrl, którego możesz użyć do pobrania rzeczywistych bajtów elementu multimedialnego. Szczegółowe informacje o dodatkowych parametrach baseUrl znajdziesz w przewodniku Wyświetlanie i pobieranie elementów multimedialnych.

  7. Wyświetlanie elementów multimedialnych: użyj ikony baseUrl w sekcji MediaFile, aby pobrać i wyświetlić treści multimedialne na urządzeniu w otoczeniu.

Istotne kwestie

Limit urządzeń i zarządzanie nimi:

  • Limity urządzeń: pamiętaj, że każdy użytkownik Twojej aplikacji może mieć maksymalnie 100 urządzeń.
  • Aktywność i tokeny urządzenia: musisz zarządzać cyklem życia urządzeń i tokenów autoryzacji użytkowników. Zastanów się, jak długo urządzenia pozostają aktywne i jak będziesz obsługiwać odświeżanie tokenów lub ponowną autoryzację, jeśli urządzenie stanie się nieaktywne lub token wygaśnie.

Więcej informacji znajdziesz w przewodniku Tworzenie urządzeń i zarządzanie nimi.

Praca z elementami multimedialnymi:

  • Wykorzystanie elementu multimedialnego: dowiedz się, jak prawidłowo pobierać i obsługiwać treść elementu multimedialnego za pomocą baseUrl, w tym wszelkie niezbędne parametry lub uwierzytelnianie.
  • Obsługa błędów: zaimplementuj niezawodną obsługę błędów w przypadku wywołań interfejsu API, w tym scenariuszy takich jak NOT_FOUND w przypadku urządzeń, FAILED_PRECONDITION, jeśli źródła multimediów nie są ustawione, i RESOURCE_EXHAUSTED, jeśli osiągnięto limity urządzeń.

Więcej informacji, w tym o zasadach dotyczących treści i filtrowaniu, znajdziesz w przewodniku Wyświetlanie i pobieranie elementów multimedialnych.

Następne kroki