Inizia a utilizzare l'API Ambient

L'API Ambient consente alla tua applicazione di connettere i dispositivi Ambient all'account Google Foto di un utente e di visualizzare le foto selezionate.

Flusso dell'API Ambient

Ecco una spiegazione dettagliata del funzionamento dell'API Ambient per connettere un dispositivo e recuperare e visualizzare elementi multimediali:

1. Cerca un dispositivo esistente (consigliato): prima di creare un nuovo dispositivo, è consigliabile controllare se ne esiste già uno per l'utente corrente. La tua applicazione deve mantenere una mappatura tra l'utente interno e il deviceId fornito da Google per tutti i dispositivi che crea tramite la tua app. Se viene trovato un deviceId per l'utente, puoi procedere all'aggiornamento del token di autorizzazione (se necessario).

2. Avvia l'autorizzazione OAuth 2.0 (e, facoltativamente, crea il dispositivo): avvia il flusso OAuth 2.0 per TV e dispositivi di input con limitazioni richiedendo un codice di autorizzazione.

   Nota: l'API Ambient supporta l'opzione per includere il parametro state nella richiesta di autorizzazione. In questo modo, l'API Ambient tenterà anche di creare un nuovo dispositivo al termine dell'autorizzazione.

3. Crea un nuovo dispositivo: l'app crea un dispositivo nell'account Google Foto di un utente chiamando CreateDevice e fornendo un UUID v4 valido.

   Dopo la creazione del dispositivo, l'API restituirà un oggetto AmbientDevice contenente un deviceId assegnato da Google. È fondamentale che la tua applicazione memorizzi questo deviceId e lo associ ai tuoi utenti.

4. Mostra settingsUri: un oggetto AmbientDevice include un settingsUri. Presenta questo URI all'utente, in genere sotto forma di codice QR, che l'utente può scansionare utilizzando il proprio dispositivo mobile. Questo URI indirizza l'utente all'app Google Foto, dove può configurare le origini multimediali (ad es. gli album) che vuole visualizzare sul proprio dispositivo Ambient.

5. Monitoraggio di mediaSourcesSet: l'applicazione deve chiamare periodicamente il metodo GetDevice, fornendo deviceId, per controllare lo stato del dispositivo in ambiente. Monitora il campo mediaSourcesSet nella risposta AmbientDevice. Inizialmente sarà false.

   Una volta che l'utente ha selezionato correttamente le origini multimediali nell'app Google Foto, questo campo assumerà il valore true.

   La risposta AmbientDevice include un pollingConfig con un valore pollInterval da utilizzare come linea guida per la frequenza di polling.

6. Recupera gli elementi multimediali: quando mediaSourcesSet restituisce true, la tua applicazione può iniziare a recuperare gli elementi multimediali selezionati dall'utente.

   Chiama il metodo ListMediaItems, fornendo deviceId. L'API restituirà un ListMediaItemsResponse contenente un elenco di oggetti AmbientMediaItem. Ogni AmbientMediaItem include dettagli come un id, createTime e un oggetto MediaFile con metadati aggiuntivi. MediaFile contiene un baseUrl che puoi utilizzare per recuperare i byte effettivi di un elemento multimediale. Consulta la guida su come elencare e recuperare gli elementi multimediali per informazioni dettagliate su altri parametri baseUrl.

7. Mostra elementi multimediali: utilizza baseUrl da MediaFile per scaricare e visualizzare i contenuti multimediali sul dispositivo Ambient.

Considerazioni importanti

Limite di dispositivi e gestione:

• Limiti dei dispositivi: tieni presente il limite di 100 dispositivi per utente della tua applicazione.
• Attività e token dei dispositivi: dovrai gestire il ciclo di vita dei dispositivi e dei token di autorizzazione utente. Valuta per quanto tempo i dispositivi rimangono attivi e come gestirai il rinnovo dei token o la loro riattivazione se un dispositivo diventa inattivo o se il token scade.

La guida su come creare e gestire i dispositivi contiene dettagli aggiuntivi.

Lavorare con gli elementi multimediali:

• Utilizzo degli elementi multimediali: scopri come recuperare e gestire correttamente i contenuti degli elementi multimediali utilizzando baseUrl, incluse eventuali autenticazioni o parametri necessari.
• Gestione degli errori: implementa una gestione degli errori solida per le chiamate API, inclusi scenari come NOT_FOUND per i dispositivi, FAILED_PRECONDITION se le sorgenti media non sono impostate e RESOURCE_EXHAUSTED se vengono raggiunti i limiti dei dispositivi.

La guida su come elencare e recuperare gli elementi multimediali contiene ulteriori dettagli.

Passaggi successivi

• Configura la tua applicazione:verifica di disporre delle credenziali necessarie e di aver configurato la tua applicazione per OAuth 2.0 per TV e dispositivi con input limitato.
• Esamina la documentazione di riferimento dell'API Ambient:consulta la documentazione di riferimento dettagliata per tutti i metodi, i parametri di richiesta e risposta e i codici di errore disponibili.