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ęć.

Proces korzystania z interfejsu Ambient API

Oto jak działa interfejs 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 podanym przez Google identyfikatorem deviceId dla wszystkich urządzeń, które użytkownik utworzy za pomocą aplikacji. Jeśli dla użytkownika zostanie znaleziony identyfikator deviceId, możesz odświeżyć jego token autoryzacji (w razie potrzeby).

2. Zainicjuj autoryzację OAuth 2.0: rozpocznij proces OAuth 2.0 dla telewizora i urządzeń z ograniczonymi możliwościami wprowadzania danych , wysyłając prośbę o kod autoryzacji.

   **Uwaga:** interfejs Ambient API obsługuje dodawanie parametru state do żądania autoryzacji, aby umożliwić uproszczony proces uwierzytelniania.

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 pomyślnym utworzeniu urządzenia interfejs API zwróci obiekt AmbientDevice zawierający przypisany przez Google identyfikator deviceId. Ważne jest, aby aplikacja przechowywała ten identyfikator deviceId i powiązała go z użytkownikami.

4. Wyświetl settingsUri: obiekt AmbientDevice zawiera settingsUri. Wyświetl ten identyfikator URI użytkownikowi, zwykle w postaci kodu QR, który użytkownik może zeskanować za pomocą urządzenia mobilnego. Ten identyfikator 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 otoczenia.

5. Sprawdź, czy mediaSourcesSet jest ustawione: aplikacja powinna okresowo wywoływać metodę GetDevice, podając identyfikator deviceId, aby sprawdzić stan urządzenia otoczenia. Monitoruj pole mediaSourcesSet w odpowiedzi AmbientDevice. Początkowo będzie ono mieć wartość false.

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

   Odpowiedź AmbientDevice zawiera pollingConfig z parametrem pollInterval, który powinien być używany jako wskazówka dotycząca częstotliwości sprawdzania.

6. Pobierz elementy multimedialne: gdy mediaSourcesSet zwróci wartość true, aplikacja może zacząć pobierać elementy multimedialne wybrane przez użytkownika.

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

7. Wyświetl elementy multimedialne: użyj baseUrl z MediaFile, aby pobrać i wyświetlić elementy multimedialne na urządzeniu otoczenia.

Istotne kwestie

Limit urządzeń i zarządzanie nimi:

• Limity urządzeń: pamiętaj o limicie 100 urządzeń na użytkownika aplikacji.
• Aktywność na urządzeniu i tokeny: musisz zarządzać cyklem życia urządzeń i tokenów autoryzacji użytkownika. 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. Ma dodatkowe szczegóły.

Praca z elementami multimedialnymi:

• Użycie elementu multimedialnego: dowiedz się, jak prawidłowo pobierać i obsługiwać element multimedialny za pomocą baseUrl, w tym wszelkie niezbędne uwierzytelnianie lub parametry.
• 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 nie ustawiono źródeł multimediów, oraz RESOURCE_EXHAUSTED, jeśli osiągnięto limity urządzeń.

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

Następne kroki

• Skonfiguruj aplikację: sprawdź, czy masz niezbędne dane logowania i czy aplikacja jest skonfigurowana pod kątem OAuth 2.0 dla telewizora i urządzeń z ograniczonymi możliwościami wprowadzania danych.
• Zapoznaj się z dokumentacją API Ambient: Zapoznaj się ze szczegółową dokumentacją API wszystkich dostępnych metod, parametrów żądań i odpowiedzi oraz kodów błędów.