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

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

  1. Verifica l'esistenza di un dispositivo (consigliato): prima di creare un nuovo dispositivo, ti consigliamo di verificare se ne esiste già uno per l'utente corrente. La tua applicazione deve mantenere un mapping tra l'utente interno e il deviceId fornito da Google per tutti i dispositivi creati tramite l'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: avvia il flusso OAuth 2.0 per TV e dispositivi di input limitati richiedendo un codice di autorizzazione.

  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 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 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. album) che vuole visualizzare sul proprio dispositivo ambient.

  5. Esegui il polling per mediaSourcesSet: la tua applicazione deve chiamare periodicamente il metodo GetDevice, fornendo il deviceId, per controllare lo stato del dispositivo ambient. 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 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 il 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. Per dettagli sui parametri baseUrl aggiuntivi, consulta la guida Elencare e recuperare gli elementi multimediali.

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

Considerazioni importanti

Limite e gestione dei dispositivi:

  • Limiti dei dispositivi: tieni presente il limite di 100 dispositivi per utente della tua applicazione.
  • Attività del dispositivo e token: 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 dei token o la riautorizzazione 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 autenticazione 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 a Elencare e recuperare gli elementi multimediali contiene ulteriori dettagli, incluse informazioni sulle norme relative ai contenuti e sul filtraggio.

Passaggi successivi