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 visualizzare le foto selezionate.

Flusso dell'API Ambient

Di seguito è riportata una suddivisione del funzionamento dell'API Ambient per connettere un dispositivo e poi recuperare e visualizzare gli elementi multimediali:

1. Controlla se esiste già un dispositivo (consigliato): prima di creare un nuovo dispositivo, è consigliabile verificare se esiste già un dispositivo per l'utente corrente. La tua applicazione deve mantenere una mappatura tra l'utente interno e l'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): inizia il flusso OAuth 2.0 per TV e dispositivi di input limitati 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à di creare un nuovo dispositivo in caso di autorizzazione riuscita.

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

   Una volta creato correttamente il 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. Visualizza settingsUri: un oggetto AmbientDevice include un settingsUri. Presenta questo URI all'utente, in genere come codice QR, che può scansionare utilizzando il proprio dispositivo mobile. Questo URI indirizza l'utente all'app Google Foto, dove può configurare le origini multimediali (ad es. album) che vuole visualizzare sul dispositivo Ambient.

5. Polling per mediaSourcesSet: la tua applicazione deve chiamare periodicamente il metodo GetDevice, fornendo deviceId, per controllare lo stato del dispositivo ambientale. 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 cambierà in true.

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

6. Recupera 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, un 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 per elencare e recuperare elementi multimediali per informazioni dettagliate su altri parametri baseUrl.

7. Visualizza elementi multimediali: utilizza baseUrl da MediaFile per scaricare e visualizzare i contenuti multimediali sul dispositivo per la casa.

Considerazioni importanti

Limite e gestione dei dispositivi:

• Limiti dei dispositivi: tieni presente il limite di 100 dispositivi per utente della tua applicazione.
• Attività e token del dispositivo: 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 gli aggiornamenti o le riautorizzazioni dei token se un dispositivo diventa inattivo o il token scade.

La guida Creare e gestire i dispositivi contiene ulteriori dettagli.

Utilizzo degli elementi multimediali:

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

La guida per elencare e recuperare elementi multimediali contiene ulteriori dettagli, incluse informazioni sulle norme relative ai contenuti e sul filtraggio.

Passaggi successivi

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