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.

Ablauf der Ambient API

Hier ist eine Aufschlüsselung der Funktionsweise der Ambient API zum Verbinden eines Geräts und zum Abrufen und Anzeigen von Media-Elementen:

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

  2. OAuth 2.0-Autorisierung initiieren: Starten Sie den OAuth 2.0-Ablauf für TV- und Geräteanwendungen mit begrenzter Eingabe , indem Sie einen Autorisierungscode anfordern.

  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 v4-UUID bereitstellt.

    Nachdem 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. Präsentieren Sie dem Nutzer diesen URI, 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 Media-Quellen (z.B. Alben) konfigurieren kann, die auf seinem Ambient-Gerät angezeigt werden sollen.

  5. Nach mediaSourcesSet suchen: Ihre Anwendung sollte regelmäßig die Methode GetDevice aufrufen und die deviceId angeben, um den Status des Ambient-Geräts zu prüfen. Behalten Sie das Feld mediaSourcesSet in der AmbientDevice-Antwort im Blick. Es ist anfangs auf „false“ gesetzt.

    Sobald der Nutzer in der Google Fotos App Media-Quellen ausgewählt hat, ändert sich dieser Wert in „true“.

    Die AmbientDevice-Antwort enthält eine pollingConfig mit einem pollInterval, das Sie als Richtlinie für die Häufigkeit der Abfragen 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 eine ListMediaItemsResponse mit einer Liste von AmbientMediaItem-Objekten zurück. Jedes AmbientMediaItem enthält Details wie eine id, createTime und ein MediaFile-Objekt mit zusätzlichen Metadaten. MediaFile enthält eine baseUrl, mit der Sie die tatsächlichen Bytes einer Mediendatei abrufen können. Weitere Informationen zu zusätzlichen baseUrl Parametern finden Sie im Leitfaden zum Auflisten und Abrufen von Media-Elementen.

  7. Media-Elemente anzeigen: Verwenden Sie die baseUrl aus MediaFile, um die Media-Inhalte auf das Ambient-Gerät herunterzuladen und dort 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 zum Erstellen und Verwalten von Geräten.

Mit Media-Elementen arbeiten:

  • Verwendung von Media-Elementen: Machen Sie sich mit dem richtigen Abrufen und Verarbeiten von Media-Elementen mithilfe von baseUrl vertraut, einschließlich aller erforderlichen Authentifizierungen oder Parameter.
  • Fehlerbehebung: 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 die Gerätelimits erreicht sind.

Weitere Informationen, einschließlich Informationen zu Inhaltsrichtlinien und Filtern, finden Sie im Leitfaden zum Auflisten und Abrufen von Media-Elementen.

Nächste Schritte