Configurare l'app per l'API Ambient

Per iniziare a utilizzare l'API Ambient, configura il progetto attivando l'API nella console API di Google e impostando un ID client OAuth 2.0. L'API Ambient utilizza OAuth 2.0 per le applicazioni per TV e dispositivi con input limitato.

La tua applicazione interagisce con l'API Ambient per conto di un utente dell'API Ambient. L'utente autorizza queste richieste API utilizzando il protocollo OAuth 2.0.

L'ID client OAuth 2.0 consente agli utenti della tua applicazione di accedere, autenticarsi e quindi utilizzare l'API Ambient. L'API Ambient non supporta gli account di servizio. Per utilizzare queste API, gli utenti devono aver eseguito l'accesso a un Account Google valido.

Configura la tua app

Innanzitutto, abilita l'API, poi richiedi un ID client OAuth 2.0.

Abilita l'API

Prima di poter utilizzare l'API Ambient, devi attivarla nel tuo progetto.

1. Vai alla console API di Google.
2. Nella barra dei menu, seleziona un progetto o creane uno nuovo.
3. Per aprire una delle API di Google Foto, seleziona API e servizi > Libreria nel menu di navigazione.
4. Cerca "API Ambient". Seleziona l'API Ambient e fai clic su Abilita.

Richiedere un ID client OAuth 2.0

Segui questi passaggi per richiedere un ID client OAuth e configurarlo per la tua applicazione. L'API Ambient utilizza OAuth 2.0 per le applicazioni per TV e dispositivi con input limitato.

1. Vai alla console API di Google e seleziona il tuo progetto.
2. Nel menu, seleziona API e servizi > Credenziali.

3. Nella pagina Credenziali, fai clic su Crea credenziali > ID client OAuth.

   Nota: se stai configurando un nuovo progetto, è possibile che ti venga chiesto di configurare la schermata per il consenso del progetto.

4. Seleziona il tipo di applicazione. In questo esempio, il tipo di applicazione è TV e dispositivi a input limitato.

5. Assegna un nome al client OAuth 2.0 e fai clic su Crea.

6. Dalla finestra di dialogo del client OAuth risultante, copia quanto segue:

   • ID client
   • Client secret

La tua app può accedere alle API Google abilitate utilizzando questi valori.

Prima di poter lanciare un'applicazione pubblica che accede all'API Ambient, la tua app deve essere esaminata da Google. Quando testi l'applicazione, sullo schermo viene visualizzato il messaggio "App non verificata" finché non viene verificata.

Dopo aver configurato l'app, puoi iniziare. Puoi esplorare le seguenti risorse o continuare a leggere per saperne di più sul flusso di autenticazione semplificato per l'API Ambient.

• Creare e gestire i dispositivi
• Elenca e recupera elementi multimediali

Modificare l'ID client

È possibile accedere alle risorse create tramite una delle API di Google Foto o modificarle solo utilizzando l'ID cliente originale utilizzato per crearle. Ad esempio, se crei un session nell'API Picker con un ID client specifico e in un secondo momento modifichi quell'ID client nella tua app, l'app perderà l'accesso a qualsiasi risorsa API creata con l'ID client precedente.

Pianifica attentamente e scegli il tipo di ID client corretto per l'API di Foto che stai utilizzando. Modifica l'ID cliente solo se assolutamente necessario per evitare problemi di accesso.

Flusso di autenticazione semplificato per l'API Ambient

Il flusso di autenticazione dell'API Ambient standard richiede agli utenti di scansionare due codici QR:

• Un primo per accedere al proprio Account Google (se non l'ha ancora fatto).
• Un secondo link al dispositivo Ambient appena creato nel suo account Google Foto, dove può selezionare gli elementi multimediali da visualizzare.

Il flusso semplificato ti consente di fornire un singolo codice QR agli utenti passando il parametro aggiuntivo state con la chiamata di autenticazione iniziale.

Quando richiedi codici dispositivo e utente nell'ambito di OAuth per dispositivi di input limitati, includere il parametro aggiuntivo state nella richiesta. Aggiungi quanto segue al parametro state:

Parametri
requestId	string Obbligatorio. Un identificatore univoco fornito dal cliente per questa richiesta. Viene utilizzato per ridurre la duplicazione delle risorse in caso di guasto della rete. Questo ID deve avere il formato di una stringa UUID (versione 4) e soddisfare i seguenti requisiti: Non deve contenere informazioni di identificazione sensibili sull'utente. Deve contenere 32 caratteri esadecimali suddivisi in cinque gruppi separati da trattini, nel formato "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (o 8-4-4-4-12).
displayName	string Facoltativo. Un nome visualizzato definito dall'utente per questo dispositivo. Sarà visibile agli utenti dalle impostazioni dell'app Google Foto, ma potrà essere modificato solo tramite questa API. I nomi visualizzati validi devono avere una lunghezza compresa tra 1 e 100 caratteri (inclusi).

Ad esempio, vedi il seguente blocco di codice:

    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"
            })
        })
    });

Una risposta corretta includerà un user_code e un verification_url, che mostrerai all'utente (molto probabilmente sotto forma di codice QR) in modo che possa accedere alla pagina su un altro dispositivo. Se includi il parametro state, quando in un secondo momento chiami createDevice con l'API Ambient, puoi saltare la presentazione di settingsUri in un secondo codice QR, poiché l'ultimo passaggio del flusso OAuth porterà automaticamente a questa posizione.

Per informazioni complete, abbiamo incluso una spiegazione più dettagliata. Puoi anche esaminare il codice nella nostra app di esempio per un esempio di utilizzo del parametro state nell'ambito di OAuth per dispositivi di input con limitazioni con l'API Ambient.

Dettagli sul flusso di autenticazione semplificato

Per comprendere appieno il flusso OAuth semplificato per l'API Ambient, è utile conoscere sia il flusso OAuth 2.0 per TV e applicazioni per dispositivi con input limitato sia il flusso dell'API Ambient standard. Di seguito sono riportati i passaggi per ogni flusso.

OAuth 2.0 per applicazioni per TV e dispositivi con input limitato:

1. L'applicazione invia una richiesta al server di autorizzazione di Google che identifica gli ambiti per i quali l'applicazione richiederà l'autorizzazione di accesso.
2. Il server risponde con diverse informazioni utilizzate nei passaggi successivi, ad esempio un codice dispositivo e un codice utente.
3. Visualizzi le informazioni che l'utente può inserire su un dispositivo separato per autorizzare la tua app.
4. L'applicazione inizia a eseguire il polling del server di autorizzazione di Google per determinare se l'utente ha autorizzato la tua app.
5. L'utente passa a un dispositivo con funzionalità di inserimento più avanzate, avvia un browser web, accede all'URL visualizzato nel passaggio 3 e inserisce un codice visualizzato anche nel passaggio 3. L'utente può quindi concedere (o negare) l'accesso alla tua applicazione.
6. La risposta successiva alla richiesta di polling contiene i token di cui la tua app ha bisogno per autorizzare le richieste per conto dell'utente. Se l'utente ha rifiutato l'accesso alla tua applicazione, la risposta non contiene token.

Flusso dell'API Ambient:

1. Controlla se è presente un token OAuth esistente, aggiornalo o richiedi un nuovo token.
2. Dopo aver ottenuto un token OAuth, crea un nuovo dispositivo.
3. Mostra settingsUri all'utente e inizia a eseguire il polling del dispositivo finché mediaSourcesSet non restituisce true.
4. L'utente accede a settingsUri e seleziona le foto che vuole condividere con la tua applicazione.
5. Una volta che mediaSourcesSet restituisce true, recupera l'elenco di mediaItems.
6. Ora puoi iniziare la presentazione o un'altra esperienza Ambient.

Entrambi i flussi includono un passaggio in cui mostri un URL all'utente, che lo naviga sul proprio dispositivo di input più completo. Se includi il parametro state nella chiamata OAuth iniziale, puoi evitare il secondo URL da visualizzare.

Questo funziona perché l'ultimo passaggio del flusso OAuth 2.0 per le applicazioni per TV e dispositivi con input limitato reindirizza normalmente l'utente a una pagina con il messaggio "Ora puoi tornare al tuo dispositivo". Se includi il parametro stato, l'ultimo passaggio del flusso tenterà di reindirizzarti a settingsUri. La tua app riceverà comunque un token OAuth. Devi utilizzare questo token per chiamare createDevice utilizzando lo stesso requestId. Una volta creato un dispositivo con lo stesso ID, il flusso OAuth iniziale reindirizzerà correttamente l'utente alla pagina corretta sul dispositivo avanzato all'interno dell'app Foto.

Tieni presente quanto segue:

• Ti consigliamo comunque di mostrare il settingsUri in caso di problemi con l'autenticazione.
• Puoi comunque utilizzare settingsUri in altri casi, ad esempio quando un utente vuole aggiornare la selezione di foto.