Erste Schritte mit der Ambient API

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

Ablauf der Ambient API

Hier eine detaillierte Beschreibung, wie die Ambient API ein Gerät verbindet und dann Medienelemente abruft und anzeigt:

  1. Nach einem vorhandenen 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 für alle Geräte, die Nutzer über Ihre App erstellen, eine Zuordnung zwischen Ihrem internen Nutzer und der von Google bereitgestellten deviceId pflegen. Wenn eine deviceId für den Nutzer gefunden wird, können Sie bei Bedarf sein Autorisierungstoken aktualisieren.

  2. OAuth 2.0-Autorisierung initiieren (und optional Gerät erstellen): Beginne den OAuth 2.0-Vorgang für Fernseher und Geräte 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 v4-UUID angibt.

    Nach erfolgreicher Geräteerstellung gibt die API ein AmbientDevice-Objekt mit einer von Google zugewiesenen deviceId zurück. Es ist wichtig, dass Ihre App diese deviceId speichert und mit Ihren Nutzern verknüpft.

  4. settingsUri anzeigen: Ein AmbientDevice-Objekt enthält ein settingsUri. Zeigen Sie diesen URI dem Nutzer an, in der Regel als QR-Code, den er mit seinem Mobilgerät scannen kann. Über diesen URI wird der Nutzer zur Google Fotos App weitergeleitet, in der er die Medienquellen (z.B. Alben) konfigurieren kann, die auf dem Bildschirmschoner seines Geräts angezeigt werden sollen.

  5. mediaSourcesSet abfragen: Ihre App sollte regelmäßig die Methode GetDevice aufrufen und dabei deviceId angeben, um den Status des Umgebungsgeräts zu prüfen. Beobachte das Feld mediaSourcesSet in der AmbientDevice-Antwort. Dieser Wert ist anfangs auf „Falsch“ festgelegt.

    Sobald der Nutzer Medienquellen in der Google Fotos App ausgewählt hat, wird dieses Feld auf „wahr“ gesetzt.

    Die AmbientDevice-Antwort enthält einen pollingConfig mit einer pollInterval, die Sie als Anhaltspunkt für die Abfragehäufigkeit verwenden sollten.

  6. Medienelemente abrufen: Wenn mediaSourcesSet „wahr“ zurückgibt, kann deine Anwendung mit dem Abrufen der vom Nutzer ausgewählten Medienelemente beginnen.

    Rufen Sie die Methode ListMediaItems auf und geben Sie deviceId an. Die API gibt ein ListMediaItemsResponse zurück, das eine Liste von AmbientMediaItem-Objekten enthält. Jedes AmbientMediaItem-Objekt enthält Details wie ein id-, ein createTime- und ein MediaFile-Objekt mit zusätzlichen Metadaten. Die MediaFile enthält eine baseUrl, mit der du die tatsächlichen Bytes eines Medienelements abrufen kannst. Weitere Informationen zu zusätzlichen baseUrl-Parametern findest du im Leitfaden zum Auflisten und Abrufen von Medienelementen.

  7. Medienelemente anzeigen: Verwenden Sie die baseUrl aus der MediaFile, um die Medieninhalte auf dem Bildschirm des Geräts herunterzuladen und anzuzeigen.

Wichtige Überlegungen

Gerätelimit und -verwaltung:

  • Gerätelimits: Beachten Sie, dass die Anzahl der Geräte pro Nutzer Ihrer App auf 100 Geräte begrenzt ist.
  • Geräteaktivitäten und Tokens: Sie müssen den Lebenszyklus von Geräten und Nutzerautorisierungstokens verwalten. Überlegen Sie, wie lange Geräte aktiv bleiben und wie Sie mit der Tokenaktualisierung oder erneuten Autorisierung umgehen, 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 Medienelementen:

  • Verwendung von Medienelementen: Hier erfährst du, wie du die Medienelemente-Inhalte mithilfe von baseUrl richtig abrufen und verarbeiten kannst, einschließlich aller erforderlichen Authentifizierungs- oder Parameter.
  • Fehlerbehandlung: Implementiere eine robuste Fehlerbehandlung für API-Aufrufe, einschließlich Szenarien wie NOT_FOUND für Geräte, FAILED_PRECONDITION, wenn keine Medienquellen festgelegt sind, und RESOURCE_EXHAUSTED, wenn die Gerätelimits erreicht werden.

Weitere Informationen finden Sie im Leitfaden Medienelemente auflisten und abrufen.

Nächste Schritte