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 wearable. Un DataItem in genere è 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 i dati solo con smartphone Android o smartwatch Wear OS watches. Se il tuo dispositivo Wear OS è associato 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, procedi nel seguente modo:

  1. Crea un oggetto PutDataRequest, specificando un percorso di 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 DataClient classe per richiedere al sistema di creare l'elemento dati.

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

Per saperne di più, consulta l'app di esempio DataLayer.

Sincronizzare i dati con una mappa dati

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

Per utilizzare una mappa dati:

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

    Nota: la stringa del percorso è un identificatore univoco per l' elemento 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 dati su cui puoi impostare i valori.
  3. Imposta i valori per la mappa dati utilizzando i put...() metodi, ad esempio putString().
  4. Se un ritardo nella sincronizzazione influisce negativamente sull'esperienza utente, chiama setUrgent().
  5. Chiama PutDataMapRequest.asPutDataRequest() per ottenere un PutDataRequest oggetto.
  6. Utilizza il metodo putDataItem della DataClient classe per richiedere al sistema di creare l'elemento dati.

    Nota: se i dispositivi portatili e wearable sono disconnessi, i dati vengono memorizzati nel buffer e sincronizzati quando la connessione viene ristabilita.

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

private fun increaseCounter(): Task<DataItem> {
    val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
        dataMap.putInt(COUNT_KEY, count++)
        asPutDataRequest()
    }
    return Wearable.getDataClient(this)
        .putDataItem(putDataReq)
}

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. In caso contrario, si verifica un'eccezione. Utilizza la GoogleApiAvailability classe, come implementata in Horologist.

Impostare la priorità di DataItem

L'API DataClient consente di effettuare richieste urgenti per la sincronizzazione degli oggetti DataItem. In genere, il sistema ritarda la consegna degli elementi dati alla rete Wear OS per migliorare la durata della batteria dei dispositivi degli utenti, ma se un ritardo nella sincronizzazione degli elementi 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 dati chiamando setUrgent().

Se non chiami setUrgent(), il sistema potrebbe ritardare la sincronizzazione degli elementi dati non urgenti fino a 30 minuti, anche se in genere il ritardo è 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.

Ascoltare gli eventi degli elementi dati

Se un lato della connessione del livello dati modifica un elemento dati, informa l'utente di eventuali modifiche sull'altro lato della connessione. Puoi farlo implementando un listener per gli eventi degli elementi dati.

Il seguente snippet di codice 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
        }
    }
}

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

Puoi anche implementare il listener come servizio. Per saperne di più, consulta Ascoltare gli eventi del livello dati.