Creare e gestire i dispositivi

Questa guida illustra come creare, gestire ed eliminare i dispositivi. Una corretta gestione dei dispositivi contribuisce a creare un'esperienza utente fluida e un utilizzo efficiente dell'API Ambient.

Creazione dispositivi

Dopo che un utente ha eseguito l'autenticazione utilizzando il flusso OAuth 2.0 per applicazioni per TV e dispositivi con input limitato, crea un dispositivo nel suo account Google Foto.

Quando la tua app crea correttamente un dispositivo utilizzando il metodo devices.create, l'API Ambient restituisce un oggetto AmbientDevice che include un id generato da Google. Archivia in modo sicuro questo id e associa agli utenti.

Creazione semplificata dei dispositivi con OAuth

L'API Ambient offre un flusso OAuth semplificato. Passando il parametro state aggiuntivo nella richiesta OAuth iniziale e chiamando devices.create con il requestId corrispondente, puoi collegare il processo di creazione del dispositivo direttamente al flusso di accesso dell'utente, semplificando l'esperienza utente riducendo il numero di codici QR che deve scansionare.

Per maggiori dettagli e un esempio, consulta la guida Flusso di autenticazione semplificato per l'API Ambient.

Limiti dei dispositivi

La tua applicazione può creare fino a 100 dispositivi per utente. Se questo limite viene superato, l'API restituisce un errore RESOURCE_EXHAUSTED.

Gestione dispositivi

Una volta creato e collegato un dispositivo all'account Google Foto di un utente, potrebbe essere necessario gestirne il ciclo di vita.

Recupero dispositivi

Per recuperare informazioni su un dispositivo specifico, utilizza il metodo devices.get con il relativo id univoco. Questa operazione è utile per controllare lo stato del dispositivo, ad esempio se mediaSourcesSet è true.

Aggiornamento dispositivi

Puoi aggiornare alcune proprietà di un dispositivo esistente, ad esempio il nome visualizzato, utilizzando il metodo devices.patch. In questo modo, gli utenti possono personalizzare i propri dispositivi e identificarli più facilmente in Google Foto.

Elimina dispositivi

Implementa una strategia per eliminare i dispositivi per una pulizia corretta e il controllo dell'utente. Puoi eliminare un dispositivo utilizzando il metodo devices.delete.

Considera i seguenti scenari per l'eliminazione dei dispositivi:

  • Disconnessione utente: se un utente disconnette la tua applicazione dal suo account Google Foto, devi eliminare il dispositivo corrispondente.
  • Dispositivi orfani: se perdi traccia di un id, ma hai ancora il requestId utilizzato durante la creazione, puoi utilizzare requestId con devices.delete per rimuovere un dispositivo orfano. In questo modo, si evitano duplicati accidentali e l'account dell'utente rimane pulito.

Considerazioni importanti e best practice

  • Ciclo di vita del dispositivo e autorizzazione utente: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 suo token scade.
  • Gestione degli errori:implementa una gestione degli errori efficace per tutte le chiamate API relative ai dispositivi. Preparati a scenari come:
    • NOT_FOUND: se un dispositivo non esiste o non è di proprietà dell'utente.
    • RESOURCE_EXHAUSTED: se superi il limite dei dispositivi.
    • ALREADY_EXISTS: se provi a creare un dispositivo con un requestId già esistente.

Passaggi successivi