Creare e gestire i dispositivi

Questa guida illustra come creare, gestire ed eliminare i dispositivi. La gestione corretta del dispositivo contribuisce a creare un'esperienza utente fluida e un uso efficiente dell'API Ambient.

Creazione dispositivi

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

Quando l'app crea correttamente un dispositivo utilizzando il metodo devices.create, l'API Ambient restituisce un oggetto AmbientDevice che include un id generato da Google. Memorizza in modo sicuro questo id e associalo ai tuoi utenti.

Creazione semplificata dei dispositivi con OAuth

L'API Ambient offre un flusso OAuth semplificato che può creare un dispositivo contemporaneamente all'autenticazione utente. Se passi il parametro state aggiuntivo nella richiesta OAuth iniziale, puoi collegare la procedura di creazione del dispositivo direttamente al flusso di accesso dell'utente, semplificando la sua esperienza riducendo il numero di codici QR da scansionare.

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

Limiti di 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, potresti dover gestire il relativo ciclo di vita.

Recupera dispositivi

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

Aggiornamento dispositivi

Puoi aggiornare determinate 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 corretta pulizia e un controllo degli utenti. Puoi eliminare un dispositivo utilizzando il metodo devices.delete.

Considera i seguenti scenari per l'eliminazione dei dispositivi:

  • Disconnessione dell'utente: se un utente scollega la tua applicazione dal suo account Google Foto, devi eliminare il dispositivo corrispondente.
  • Dispositivi orfani: se perdi il controllo di un id, ma hai ancora il requestId utilizzato durante la creazione, puoi utilizzare il 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 dei dispositivi 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 il rinnovo dei token o la loro nuova autorizzazione se un dispositivo diventa inattivo o se il 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 di dispositivi.
    • ALREADY_EXISTS: se provi a creare un dispositivo con un requestId che esiste già.

Passaggi successivi