Sincronizzare gli elementi di dati con l'API Data Layer

Un DataItem definisce l'interfaccia utilizzata dal sistema per sincronizzare i dati tra dispositivi portatili e indossabili. Un DataItem è generalmente costituito dai seguenti componenti:

  • Payload: un array di byte che puoi impostare con i dati, consentendoti di eseguire la serializzazione e la deserializzazione degli oggetti. La dimensione del payload è limitata a 100 kB.
  • Percorso:una stringa univoca che deve iniziare con una barra, ad esempio "/path/to/data".

Nota:L'API Data Layer può inviare messaggi e sincronizzare dati solo con smartphone Android o smartwatch Wear OS. Se il tuo dispositivo Wear OS è accoppiato a un dispositivo iOS, l'API Data Layer non funzionerà.

Per questo motivo, non utilizzare l'API Data Layer come metodo principale per comunicare con una rete. Segui invece lo stesso pattern di un'app mobile, con alcune piccole differenze.

In genere non implementi DataItem direttamente. Invece, esegui le seguenti operazioni:

  1. Crea un oggetto PutDataRequest, specificando un percorso stringa per identificare in modo univoco l'elemento.
  2. Chiama setData() per impostare il payload.
  3. Se un ritardo nella sincronizzazione influisce negativamente sull'esperienza utente, chiama setUrgent().
  4. Utilizza il metodo putDataItem della classe DataClient per richiedere al sistema di creare l'elemento di dati.

Quando richiedi elementi di dati, il sistema restituisce oggetti che implementano correttamente l'interfaccia DataItem. Tuttavia, anziché lavorare con byte non elaborati utilizzando setData(), ti consigliamo di utilizzare una mappa dei dati, che espone un elemento di dati con un'interfaccia simile a Bundle.

Per ulteriori informazioni, consulta l'app DataLayer Sample.

Sincronizzare i dati con una mappa dei dati

Se possibile, utilizza la classe DataMap. Questo approccio ti consente di lavorare con gli elementi di dati sotto forma di Bundle Android, in modo che il sistema esegua la serializzazione e la deserializzazione degli oggetti per te e tu possa manipolare i dati con coppie chiave-valore.

Per utilizzare una mappa dei dati:

  1. Crea un oggetto PutDataMapRequest, impostando il percorso dell'elemento di dati.

    Nota:la stringa del percorso è un identificatore univoco per l'elemento di dati che ti consente di accedervi da entrambi i lati della connessione. Il percorso deve iniziare con una barra. Se utilizzi dati gerarchici nella tua app, crea uno schema di percorso che corrisponda alla struttura dei dati.

  2. Chiama PutDataMapRequest.getDataMap() per ottenere una mappa dei dati su cui puoi impostare i valori.
  3. Imposta i valori per la mappa dei dati utilizzando i metodi put...(), ad esempio putString().
  4. Se un ritardo nella sincronizzazione influisce negativamente sull'esperienza utente, chiama setUrgent().
  5. Chiama PutDataMapRequest.asPutDataRequest() per ottenere un oggetto PutDataRequest.
  6. Utilizza il metodo putDataItem della classe DataClient per richiedere al sistema di creare l'elemento di dati.

    Nota:Se lo smartphone e i dispositivi indossabili sono disconnessi, i dati vengono memorizzati nel buffer e sincronizzati quando la connessione viene ristabilita.

Il metodo increaseCounter() nel seguente esempio mostra come creare una mappa dei dati e inserirvi i dati:

private fun increaseCounter() {
    val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
        dataMap.putInt(COUNT_KEY, count++)
        asPutDataRequest()
    }
    val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)
}
DataLayerActivity.kt

Per saperne di più sulla gestione di Tasks, consulta la documentazione di riferimento.

Attenzione: prima di utilizzare l'API Wearable Data Layer, verifica che sia disponibile su un dispositivo, altrimenti si verifica un'eccezione. Utilizza la classe GoogleApiAvailability, come implementato in Horologist.

Imposta la priorità di DataItem

L'API DataClient consente richieste urgenti di sincronizzazione degli oggetti DataItem. Normalmente, il sistema ritarda la distribuzione degli elementi di dati alla rete Wear OS per migliorare la durata della batteria dei dispositivi degli utenti, ma se un ritardo nella sincronizzazione degli elementi di dati influisce negativamente sull'esperienza utente, puoi contrassegnarli come urgenti. Ad esempio, in un'app di controllo remoto in cui l'utente si aspetta che le sue azioni vengano riflesse immediatamente, puoi fare in modo che il sistema sincronizzi immediatamente gli elementi di dati chiamando setUrgent().

Se non chiami setUrgent(), il sistema potrebbe ritardare la sincronizzazione degli elementi di dati non urgenti fino a 30 minuti, anche se di solito il ritardo è solo di pochi minuti. L'urgenza predefinita è non urgente, quindi devi utilizzare setUrgent() se devi mantenere il comportamento di sincronizzazione immediata delle versioni precedenti dell'API Wear OS.

Ascolta gli eventi degli elementi di dati

Se un lato della connessione del livello dati modifica un elemento di dati, comunica all'utente le modifiche apportate all'altro lato della connessione. Puoi farlo implementando un listener per gli eventi degli elementi di dati.

Lo snippet di codice nell'esempio seguente invia una notifica all'app quando il valore del contatore definito nell'esempio precedente cambia:

override fun onDataChanged(dataEvents: DataEventBuffer) {

    dataEvents.forEach { event ->
        // DataItem changed
        if (event.type == DataEvent.TYPE_CHANGED) {
            event.dataItem.also { item ->
                if (item.uri.path?.compareTo("/count") == 0) {
                    DataMapItem.fromDataItem(item).dataMap.apply {
                        updateCount(getInt(COUNT_KEY))
                    }
                }
            }
        } else if (event.type == DataEvent.TYPE_DELETED) {
            // DataItem deleted
        }
    }
}
DataLayerActivity.kt

Questa attività implementa l'interfaccia DataClient.OnDataChangedListener. L'attività si aggiunge come listener per gli eventi degli elementi di dati all'interno del metodo onResume() e rimuove il listener nel metodo onPause(). Per visualizzare un'implementazione che utilizza immagini, modelli di visualizzazione e servizi, consulta l'app DataLayer Sample.

Puoi anche implementare il listener come servizio. Per maggiori informazioni, consulta la pagina Ascoltare gli eventi del livello dati.