App für die Ambient API konfigurieren

Wenn Sie die Ambient API verwenden möchten, müssen Sie Ihr Projekt konfigurieren. Aktivieren Sie dazu die API in der Google API Console und richten Sie eine OAuth 2.0-Client-ID ein. Die Ambient API verwendet OAuth 2.0 für TV- und Geräteanwendungen mit begrenzter Eingabe.

Ihre Anwendung interagiert im Namen eines Nutzers der Ambient API mit der Ambient API. Der Nutzer autorisiert diese API-Anfragen mit dem OAuth 2.0-Protokoll.

Mit der OAuth 2.0-Client-ID können sich die Nutzer Ihrer Anwendung anmelden, authentifizieren und so die Ambient API verwenden. Die Ambient API unterstützt keine Dienstkonten. Um diese APIs zu verwenden, müssen Nutzer in einem gültigen Google-Konto angemeldet sein.

Eigene App konfigurieren

Aktivieren Sie zuerst die API und fordern Sie dann eine OAuth 2.0-Client-ID an.

API aktivieren

Bevor Sie die Ambient API verwenden können, müssen Sie sie in Ihrem Projekt aktivieren.

  1. Rufen Sie die Google API Console auf.
  2. Wählen Sie in der Menüleiste ein Projekt aus oder erstellen Sie ein neues.
  3. Wenn Sie eine der Google Fotos APIs öffnen möchten, wählen Sie im Navigationsmenü APIs & Dienste > Bibliothek aus.
  4. Suchen Sie nach „Ambient API“. Wählen Sie die Ambient API aus und klicken Sie auf Aktivieren.

OAuth 2.0-Client-ID anfordern

So fordern Sie eine OAuth-Client-ID an und konfigurieren sie für Ihre Anwendung: Die Ambient API verwendet OAuth 2.0 für TV- und Geräteanwendungen mit begrenzter Eingabe.

  1. Rufen Sie die Google API Console auf und wählen Sie Ihr Projekt aus.
  2. Wählen Sie im Menü APIs und Dienste > Anmeldedaten aus.

  3. Klicken Sie auf der Seite Anmeldedaten auf Anmeldedaten erstellen > OAuth-Client-ID.

  4. Wählen Sie den Anwendungstyp aus. In diesem Beispiel ist der Anwendungstyp Fernseher und Geräte mit begrenzter Eingabe.

  5. Geben Sie einen Namen für Ihren OAuth 2.0-Client ein und klicken Sie auf Erstellen.

  6. Kopieren Sie im folgenden Dialogfeld „OAuth-Client“ Folgendes:

    • Client-ID
    • Clientschlüssel

Ihre App kann mit diesen Werten auf die aktivierten Google APIs zugreifen.

Bevor Sie eine öffentliche Anwendung veröffentlichen können, die auf die Ambient API zugreift, muss Ihre Anwendung von Google überprüft werden. Wenn Sie Ihre App testen, wird auf dem Bildschirm die Meldung „Nicht bestätigte App“ angezeigt, bis die App überprüft wurde.

Nachdem Sie Ihre App konfiguriert haben, können Sie loslegen. Sie können sich die folgenden Ressourcen ansehen oder mehr über den vereinfachten Authentifizierungsablauf für die Ambient API erfahren.

Client-ID ändern

Auf Ressourcen, die über eine der Google Fotos APIs erstellt wurden, kann nur mit der ursprünglichen Client-ID zugegriffen oder sie nur so geändert werden. Wenn Sie beispielsweise eine session in der Picker API mit einer bestimmten Client-ID erstellen und diese Client-ID später in Ihrer App ändern, verliert Ihre App den Zugriff auf alle API-Ressourcen, die mit der vorherigen Client-ID erstellt wurden.

Planen Sie sorgfältig und wählen Sie den richtigen Client-ID-Typ für die von Ihnen verwendete Google Fotos API aus. Ändern Sie Ihre Client-ID nur, wenn dies unbedingt erforderlich ist, um Zugriffsprobleme zu vermeiden.

Optimierter Authentifizierungsablauf für die Ambient API

Für den standardmäßigen Authentifizierungsablauf der Ambient API müssen Nutzer zwei QR-Codes scannen:

  • Melden Sie sich zuerst in Ihrem Google-Konto an, falls Sie noch nicht angemeldet sind.
  • Eine zweite, die mit dem neu erstellten Ambient-Gerät in ihrem Google Fotos-Konto verknüpft ist, in dem sie Medienelemente auswählen können, die angezeigt werden sollen.

Mit dem optimierten Ablauf können Sie Ihren Nutzern einen einzigen QR-Code zur Verfügung stellen, indem Sie den zusätzlichen Parameter state mit Ihrem ersten Authentifizierungsaufruf übergeben.

Wenn du Geräte- und Nutzercodes im Rahmen von OAuth für Geräte mit begrenzter Eingabe anforderst, musst du den zusätzlichen Parameter state in deine Anfrage aufnehmen. Fügen Sie dem state-Parameter Folgendes hinzu:

Parameter
requestId

string

Erforderlich. Eine vom Kunden bereitgestellte eindeutige Kennung für diese Anfrage. So wird die Ressourcenduplizierung bei einem Netzwerkausfall vermieden.

Diese ID muss das Format eines UUID-Strings (Version 4) haben und den folgenden Anforderungen entsprechen:

  • Es dürfen keine vertraulichen personenidentifizierbaren Informationen über den Nutzer enthalten sein.
  • Muss 32 Hexadezimalzeichen enthalten, die in fünf Gruppen unterteilt und durch Bindestriche getrennt sind, im Format „xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx“ (oder 8-4-4-4-12).
displayName

string

Optional. Ein benutzerdefinierter Anzeigename für dieses Gerät.

Dieser ist für Nutzer in den Einstellungen der Google Fotos App sichtbar, kann aber nur über diese API bearbeitet werden.

Gültige Anzeigenamen müssen zwischen 1 und 100 Zeichen lang sein.

Beispiel:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Eine erfolgreiche Antwort enthält einen user_code und einen verification_url, die du dem Nutzer zeigst (höchstwahrscheinlich als QR-Code), damit er dorthin auf einem anderen Gerät navigieren kann. Wenn du den Parameter state einschließt, kannst du beim späteren Aufruf von createDevice mit der Ambient API das Präsentieren der settingsUri in einem zweiten QR-Code überspringen, da du im letzten Schritt des OAuth-Vorgangs automatisch zu diesem Speicherort weitergeleitet wirst.

Weitere Informationen finden Sie in der ausführlichen Erklärung. In der Beispiel-App findest du ein Beispiel für die Verwendung des Parameters state im Rahmen von OAuth für Geräte mit begrenzter Eingabe mit der Ambient API.

Details zum optimierten Authentifizierungsvorgang

Um den optimierten OAuth-Ablauf für die Ambient API vollständig zu verstehen, ist es hilfreich, sowohl den OAuth 2.0-Ablauf für TV- und Geräteanwendungen mit begrenzter Eingabe als auch den Standardablauf der Ambient API zu kennen. Nachfolgend werden die entsprechenden Vorgehensweisen beschrieben.

OAuth 2.0 für TV- und Geräteanwendungen mit begrenzter Eingabe:

  1. Ihre Anwendung sendet eine Anfrage an den Autorisierungsserver von Google, in der die Bereiche angegeben sind, für die Ihre Anwendung die Zugriffsberechtigung anfordert.
  2. Der Server antwortet mit mehreren Informationen, die in den nachfolgenden Schritten verwendet werden, z. B. einem Gerätecode und einem Nutzercode.
  3. Sie zeigen Informationen an, die der Nutzer auf einem anderen Gerät eingeben kann, um Ihre App zu autorisieren.
  4. Ihre Anwendung beginnt, den Autorisierungsserver von Google zu pollen, um zu ermitteln, ob der Nutzer Ihre App autorisiert hat.
  5. Der Nutzer wechselt zu einem Gerät mit erweiterten Eingabemöglichkeiten, startet einen Webbrowser, ruft die in Schritt 3 angezeigte URL auf und gibt einen Code ein, der ebenfalls in Schritt 3 angezeigt wird. Der Nutzer kann dann den Zugriff auf Ihre Anwendung gewähren oder verweigern.
  6. Die nächste Antwort auf Ihre Abfrageanfrage enthält die Tokens, die Ihre App benötigt, um Anfragen im Namen des Nutzers zu autorisieren. Wenn der Nutzer den Zugriff auf Ihre Anwendung abgelehnt hat, enthält die Antwort keine Tokens.

Ablauf der Ambient API:

  1. Prüfe, ob ein OAuth-Token vorhanden ist, und aktualisiere es oder fordere ein neues an.
  2. Nachdem Sie ein OAuth-Token erhalten haben, erstellen Sie ein neues Gerät.
  3. Zeige dem Nutzer die settingsUri an und beginne, das Gerät zu zyklisch abfragen, bis mediaSourcesSet „wahr“ zurückgibt.
  4. Der Nutzer ruft die settingsUri auf und wählt die Fotos aus, die er für Ihre App freigeben möchte.
  5. Sobald mediaSourcesSet „wahr“ zurückgibt, rufe die Liste der mediaItems ab.
  6. Jetzt können Sie die Diashow oder andere Bildschirmschoner starten.

Beide Abläufe umfassen einen Schritt, bei dem Sie dem Nutzer eine URL anzeigen und er sich dort mit seinem Eingabegerät mit mehr Funktionen bewegt. Wenn du den Parameter state in deinen ersten OAuth-Aufruf aufnimmst, kannst du die zweite URL vermeiden, die du anzeigen musst.

Das funktioniert, weil der Nutzer im letzten Schritt des OAuth 2.0-Workflows für TV- und Geräteanwendungen mit begrenzter Eingabe normalerweise zu einer Seite weitergeleitet wird, auf der steht: „Sie können jetzt zu Ihrem Gerät zurückkehren.“ Durch den Parameter „status“ wird im letzten Schritt des Ablaufs versucht, Sie zur settingsUri weiterzuleiten. Ihre App erhält weiterhin ein OAuth-Token. Du solltest dieses Token verwenden, um createDevice mit derselben requestId aufzurufen. Sobald ein Gerät mit derselben ID erstellt wurde, wird der Nutzer über den ersten OAuth-Ablauf erfolgreich auf die richtige Seite auf dem Gerät mit erweiterten Funktionen in der Fotos App weitergeleitet.

Beachten Sie dabei Folgendes:

  • Es ist jedoch empfehlenswert, die settingsUri anzuzeigen, falls Probleme mit der Authentifizierung auftreten.
  • Sie können das settingsUri aber auch in anderen Fällen verwenden, z. B. wenn ein Nutzer seine Fotoauswahl aktualisieren möchte.