Sincronizzare gli elementi di dati con l'API Data Layer

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

  • Payload: un array di byte che puoi impostare con i dati, permettendoti di serializzare gli oggetti la deserializzazione. 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 Wear OS smartwatch. Se il tuo dispositivo Wear OS è accoppiato a un dispositivo iOS, l'API Data Layer non funzionano.

Per questo motivo, non utilizzare l'API Data Layer come è il modo principale di comunicare con una rete. Segui invece le Lo stesso schema di un'app mobile, con alcune piccole differenze.

In genere non implementi DataItem strato Add. Puoi invece procedere nel seguente modo:

  1. Crea un Oggetto PutDataRequest, che specifica un percorso di stringa per identificare in modo univoco dell'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 del DataClient per richiedere al sistema di creare l'elemento dati.

Quando richiedi elementi di dati, il sistema restituisce gli oggetti che implementano correttamente i interfaccia di DataItem. Tuttavia, invece di lavorare con i byte non elaborati utilizzando setData(), ti consigliamo utilizzare una mappa dati, che espone un elemento di dati con un'interfaccia di tipo Bundle.

Per ulteriori informazioni, consulta Esempio di strato dati.

Sincronizzare i dati con una mappa di dati

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

Per utilizzare una mappa di dati:

  1. Crea un PutDataMapRequest, che imposta il percorso dell'elemento dati.

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

  2. Chiama PutDataMapRequest.getDataMap() per ottenere una mappa dei dati che su come impostare i valori.
  3. Imposta i valori per la mappa 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 PutDataRequest.
  6. Utilizza il metodo putDataItem del DataClient per richiedere al sistema di creare l'elemento 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() nell'esempio seguente mostra come creare un oggetto mappa e inserisci dati al suo interno:

Kotlin

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity() {

    private lateinit var dataClient: DataClient
    private var count = 0
    ...
    // Create a data map and put data in it
    private fun increaseCounter() {
        val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
            dataMap.putInt(COUNT_KEY, count++)
            asPutDataRequest()
        }
        val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)
    }
    ...
}

Java

public class MainActivity extends Activity {
    private static final String COUNT_KEY = "com.example.key.count";
    private DataClient dataClient;
    private int count = 0;
    ...
    // Create a data map and put data in it
    private void increaseCounter() {
        PutDataMapRequest putDataMapReq = PutDataMapRequest.create("/count");
        putDataMapReq.getDataMap().putInt(COUNT_KEY, count++);
        PutDataRequest putDataReq = putDataMapReq.asPutDataRequest();
        Task<DataItem> putDataTask = dataClient.putDataItem(putDataReq);
    }
  ...
}

Per ulteriori informazioni sulla gestione Tasks, consulta le documentazione di riferimento.

Imposta priorità DataItem

Lo L'API DataClient consente richieste urgenti di sincronizzazione dei DataItem di oggetti strutturati. Di solito, il sistema ritarda la consegna degli elementi di dati alla rete Wear OS per aumentare la durata della batteria dei dispositivi degli utenti, Se un ritardo nella sincronizzazione degli elementi di dati influisce negativamente sull'esperienza utente, puoi contrassegnare come urgenti. Ad esempio, in un'app di controllo remoto in cui l'utente si aspetta azioni siano immediatamente visibili, puoi fare in modo che il sistema sincronizzi gli elementi dati immediatamente chiamando setUrgent().

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

Monitora gli eventi degli elementi dati

Se un lato della connessione del livello dati modifica un elemento di dati, invia una notifica all'utente di eventuali modifiche dall'altro lato della connessione. Puoi farlo implementando un listener per gli eventi elemento dati.

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

Kotlin

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity(), DataClient.OnDataChangedListener {

    private var count = 0

    override fun onResume() {
        super.onResume()
        Wearable.getDataClient(this).addListener(this)
    }

    override fun onPause() {
        super.onPause()
        Wearable.getDataClient(this).removeListener(this)
    }

    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
            }
        }
    }

    // Method to update the count
    private fun updateCount(int: Int) { ... }
    ...
}

Java

public class MainActivity extends Activity implements DataClient.OnDataChangedListener {
    private static final String COUNT_KEY = "com.example.key.count";
    private int count = 0;

    @Override
    protected void onResume() {
        super.onResume();
        Wearable.getDataClient(this).addListener(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        Wearable.getDataClient(this).removeListener(this);
    }

    @Override
    public void onDataChanged(DataEventBuffer dataEvents) {
        for (DataEvent event : dataEvents) {
            if (event.getType() == DataEvent.TYPE_CHANGED) {
                // DataItem changed
                DataItem item = event.getDataItem();
                if (item.getUri().getPath().compareTo("/count") == 0) {
                    DataMap dataMap = DataMapItem.fromDataItem(item).getDataMap();
                    updateCount(dataMap.getInt(COUNT_KEY));
                }
            } else if (event.getType() == DataEvent.TYPE_DELETED) {
                // DataItem deleted
            }
        }
    }

    // Method to update the count
    private void updateCount(int c) { ... }
    ...
}

Questa attività implementa DataClient.OnDataChangedListener. L'attività si aggiunge come listener per gli eventi elemento dati all'interno il metodo onResume() e rimuove il listener nel Metodo onPause(). Per vedere un'implementazione utilizzando immagini, visualizzare modelli e consulta l'esempio di Livelli dati dell'app.

Puoi anche implementare il listener come servizio. Per ulteriori informazioni, vedi Ascolta il livello dati eventi.