Menyinkronkan item data dengan Data Layer API

DataItem mendefinisikan antarmuka yang digunakan sistem untuk menyinkronkan data antara perangkat genggam dan wearable. DataItem umumnya terdiri atas komponen berikut:

  • Payload: Array byte yang dapat ditetapkan dengan data, sehingga memungkinkan Anda melakukan serialisasi dan deserialisasi objek Anda sendiri. Ukuran payload dibatasi hingga 100 KB.
  • Jalur: String unik yang harus diawali dengan garis miring, seperti "/path/to/data".

Catatan: Data Layer API hanya bisa mengirim pesan dan menyinkronkan data dengan ponsel Android atau smartwatch Wear OS. Jika perangkat Wear OS disambungkan dengan perangkat iOS, Data Layer API tidak akan berfungsi.

Karena alasan ini, jangan menggunakan Data Layer API sebagai cara utama untuk berkomunikasi dengan jaringan. Sebagai gantinya, ikuti pola yang sama seperti aplikasi seluler, dengan beberapa perbedaan kecil.

Anda tidak perlu mengimplementasikan DataItem secara langsung. Sebagai gantinya, lakukan langkah berikut:

  1. Buat objek PutDataRequest, yang menentukan jalur string untuk mengidentifikasi item secara unik.
  2. Panggil setData() untuk menetapkan payload.
  3. Jika penundaan sinkronisasi akan berdampak negatif pada pengalaman pengguna, panggil setUrgent().
  4. Gunakan metode putDataItem dari class DataClient untuk meminta agar sistem membuat item data.

Saat meminta item data, sistem menampilkan objek yang mengimplementasikan antarmuka DataItem dengan benar. Namun, daripada menggunakan byte mentah menggunakan setData(), sebaiknya Anda menggunakan peta data, yang mengekspos item data dengan antarmuka seperti Bundle.

Untuk mengetahui informasi selengkapnya, lihat aplikasi Contoh DataLayer.

Menyinkronkan data dengan peta data

Jika memungkinkan, gunakan class DataMap. Pendekatan ini memungkinkan Anda menggunakan item data dalam bentuk Bundle Android, sehingga sistem melakukan serialisasi dan deserialisasi objek untuk Anda, dan Anda dapat memanipulasi data dengan key-value pair.

Untuk menggunakan peta data:

  1. Buat objek PutDataMapRequest, yang menetapkan jalur item data.

    Catatan: String jalur adalah ID unik untuk item data yang memungkinkan Anda mengaksesnya dari sisi koneksi mana pun. Jalur harus diawali dengan garis miring. Jika Anda menggunakan data hierarkis di aplikasi, buat skema jalur yang cocok dengan struktur data tersebut.

  2. Panggil PutDataMapRequest.getDataMap() untuk mendapatkan peta data tempat Anda dapat menetapkan nilai.
  3. Tetapkan nilai untuk peta data menggunakan metode put...(), seperti putString().
  4. Jika penundaan sinkronisasi akan berdampak negatif pada pengalaman pengguna, panggil setUrgent().
  5. Panggil PutDataMapRequest.asPutDataRequest() untuk mendapatkan objek PutDataRequest.
  6. Gunakan metode putDataItem dari class DataClient untuk meminta agar sistem membuat item data.

    Catatan: Jika sambungan perangkat handset dan wearable terputus, data akan di-buffer dan disinkronkan saat tersambung kembali.

Metode increaseCounter() dalam contoh berikut menunjukkan cara membuat peta data dan memasukkan data ke dalamnya:

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);
    }
  ...
}

Untuk informasi selengkapnya tentang penanganan Tasks, lihat dokumentasi referensi.

Menetapkan prioritas DataItem

DataClient API memungkinkan permintaan mendesak untuk sinkronisasi objek DataItem. Biasanya, sistem menunda pengiriman item data ke jaringan Wear OS guna meningkatkan masa pakai baterai untuk perangkat pengguna, tetapi jika penundaan sinkronisasi item data berdampak negatif pada pengalaman pengguna, Anda dapat menandainya sebagai mendesak. Misalnya, pada aplikasi kontrol jarak jauh yang langsung mencerminkan tindakan pengguna, Anda dapat membuat sistem segera menyinkronkan item data dengan memanggil setUrgent().

Jika Anda tidak memanggil setUrgent(), sistem mungkin menunda hingga 30 menit sebelum menyinkronkan item data yang tidak mendesak, meskipun biasanya Anda dapat mengharapkan penundaan terjadi dalam beberapa menit saja. Urgensi default tidak mendesak, jadi Anda harus menggunakan setUrgent() jika perlu mempertahankan perilaku sinkronisasi langsung dari Wear OS API versi sebelumnya.

Memproses peristiwa item data

Jika satu sisi koneksi lapisan data mengubah item data, beri tahu pengguna tentang setiap perubahan pada sisi lain koneksi. Anda dapat melakukannya dengan mengimplementasikan pemroses untuk peristiwa item data.

Cuplikan kode dalam contoh berikut memberi tahu aplikasi bila nilai penghitung yang ditentukan dalam contoh sebelumnya berubah:

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) { ... }
    ...
}

Aktivitas ini mengimplementasikan antarmuka DataClient.OnDataChangedListener. Aktivitas ini menambahkan diri sebagai pemroses untuk peristiwa item data dalam metode onResume() dan menghapus pemroses dalam metode onPause(). Untuk melihat implementasi menggunakan gambar, melihat model, dan lihat Contoh DataLayer .

Anda juga dapat mengimplementasikan pemroses sebagai layanan. Untuk mengetahui informasi selengkapnya, lihat Memproses peristiwa Lapisan Data.