Erste Schritte mit der Ambient API

Mit der Ambient API kann Ihre Anwendung Ambient-Geräte mit dem Google Fotos-Konto eines Nutzers verbinden und die ausgewählten Fotos anzeigen.

Ambient API-Ablauf

So funktioniert die Ambient API, um ein Gerät zu verbinden und dann Media-Elemente abzurufen und anzuzeigen:

  1. Nach vorhandenem Gerät suchen (empfohlen): Bevor Sie ein neues Gerät erstellen, sollten Sie prüfen, ob für den aktuellen Nutzer bereits ein Gerät vorhanden ist. Ihre Anwendung sollte eine Zuordnung zwischen Ihrem internen Nutzer und der von Google bereitgestellten deviceId für alle Geräte aufrechterhalten, die über Ihre App erstellt werden. Wenn eine deviceId für den Nutzer gefunden wird, können Sie das Autorisierungstoken des Nutzers aktualisieren (falls erforderlich).

  2. OAuth 2.0-Autorisierung starten (und optional Gerät erstellen): Starte den OAuth 2.0-Vorgang für TV- und Geräteanwendungen mit begrenzter Eingabe, indem du einen Autorisierungscode anforderst.

  3. Neues Gerät erstellen: Ihre App erstellt ein Gerät im Google Fotos-Konto eines Nutzers, indem sie CreateDevice aufruft und eine gültige UUID der Version 4 bereitstellt.

    Wenn das Gerät erfolgreich erstellt wurde, gibt die API ein AmbientDevice-Objekt mit einer von Google zugewiesenen deviceId zurück. Es ist wichtig, dass Ihre Anwendung diese deviceId speichert und sie Ihren Nutzern zuordnet.

  4. settingsUri anzeigen: Ein AmbientDevice-Objekt enthält ein settingsUri. Stellen Sie dem Nutzer diesen URI zur Verfügung, in der Regel als QR-Code, den der Nutzer mit seinem Mobilgerät scannen kann. Dieser URI leitet den Nutzer zur Google Fotos App weiter, wo er die Medienquellen (z.B. Alben) konfigurieren kann, die auf seinem Ambient-Gerät angezeigt werden sollen.

  5. Abrufen von mediaSourcesSet: Ihre Anwendung sollte regelmäßig die Methode GetDevice mit dem deviceId aufrufen, um den Status des Ambient-Geräts zu prüfen. Behalten Sie das Feld mediaSourcesSet in der AmbientDevice-Antwort im Blick. Der Wert ist anfangs „false“.

    Sobald der Nutzer in der Google Fotos App erfolgreich Medienquellen ausgewählt hat, ändert sich dieses Feld in „true“.

    Die AmbientDevice-Antwort enthält ein pollingConfig mit einem pollInterval, das Sie als Richtlinie für Ihre Abfragehäufigkeit verwenden sollten.

  6. Media-Elemente abrufen: Wenn mediaSourcesSet „true“ zurückgibt, kann Ihre Anwendung mit dem Abrufen der vom Nutzer ausgewählten Media-Elemente beginnen.

    Rufen Sie die Methode ListMediaItems auf und geben Sie die deviceId an. Die API gibt ein ListMediaItemsResponse zurück, das eine Liste von AmbientMediaItem-Objekten enthält. Jedes AmbientMediaItem enthält Details wie ein id, ein createTime und ein MediaFile-Objekt mit zusätzlichen Metadaten. Der MediaFile enthält einen baseUrl, mit dem Sie die tatsächlichen Byte eines Media-Elements abrufen können. Weitere Informationen zu zusätzlichen baseUrl-Parametern finden Sie in der Anleitung zum Auflisten und Abrufen von Media-Elementen.

  7. Media-Elemente anzeigen: Verwende die baseUrl aus der MediaFile, um die Media-Inhalte auf dem Ambient-Gerät herunterzuladen und anzuzeigen.

Wichtige Überlegungen

Gerätelimit und ‑verwaltung:

  • Gerätelimits: Beachten Sie das Limit von 100 Geräten pro Nutzer Ihrer Anwendung.
  • Geräteaktivität und Tokens: Sie müssen den Lebenszyklus von Geräten und Nutzerautorisierungstokens verwalten. Überlegen Sie, wie lange Geräte aktiv bleiben und wie Sie Tokenaktualisierungen oder eine erneute Autorisierung handhaben, wenn ein Gerät inaktiv wird oder das Token abläuft.

Weitere Informationen finden Sie im Leitfaden Geräte erstellen und verwalten.

So arbeiten Sie mit Media-Elementen:

  • Verwendung von Media-Elementen: Hier erfahren Sie, wie Sie die Inhalte von Media-Elementen mit der baseUrl richtig abrufen und verarbeiten, einschließlich aller erforderlichen Authentifizierungen oder Parameter.
  • Fehlerbehandlung: Implementieren Sie eine robuste Fehlerbehandlung für API-Aufrufe, einschließlich Szenarien wie NOT_FOUND für Geräte, FAILED_PRECONDITION, wenn keine Media-Quellen festgelegt sind, und RESOURCE_EXHAUSTED, wenn Gerätelimits erreicht sind.

Der Leitfaden zum Auflisten und Abrufen von Media-Elementen enthält weitere Informationen, einschließlich Informationen zur Inhaltsrichtlinie und zum Filtern.

Nächste Schritte