Mengekspos data ke detail

Aplikasi penyedia data menampilkan informasi ke detail tampilan jam, yang menyediakan kolom berisi teks, string, gambar, dan angka.

Layanan penyedia data memperluas ComplicationProviderService untuk menayangkan informasi yang berguna ke tampilan jam secara langsung.

Membuat project penyedia data

Untuk membuat project di Android Studio bagi aplikasi penyedia data Anda, selesaikan langkah-langkah berikut:

  1. Klik File > New > New project.
  2. Di jendela Project Template, klik tab Wear OS, pilih No Activity, lalu klik Next.
  3. Di jendela Configure Your Project, beri nama project Anda, isi informasi project standar, lalu klik Finish.
  4. Android Studio akan membuat project dengan modul aplikasi untuk penyedia data Anda. Untuk informasi selengkapnya tentang project di Android Studio, lihat Membuat Project.
  5. Mulai aplikasi penyedia data Anda dengan membuat class baru yang memperluas BroadcastReceiver. Fungsi class tersebut adalah memproses permintaan update detail dari sistem Wear OS. Selain itu, buat juga class baru yang memperluas ComplicationProviderService untuk menyediakan data seperti yang diminta oleh detail yang sesuai. Untuk mengetahui informasi selengkapnya, lihat referensi berikut:

    Catatan: Menambahkan aktivitas untuk penyedia data bersifat opsional. Misalnya, Anda mungkin menginginkan aktivitas yang diluncurkan hanya saat pengguna mengetuk sebuah detail.

Mengimplementasikan metode untuk permintaan update

Ketika data detail diperlukan, sistem Wear OS akan mengirimkan permintaan update ke penyedia data Anda. Permintaan diterima oleh BroadcastReceiver Anda. Untuk merespons permintaan update, penyedia data Anda harus mengimplementasikan metode onComplicationUpdate() dari class ComplicationProviderService.

Sistem Wear OS memanggil onComplicationUpdate() saat memerlukan data dari penyedia Anda—misalnya ketika detail yang menggunakan penyedia Anda menjadi aktif atau ketika jumlah waktu yang ditentukan telah berlalu. Objek ini meneruskan objek ComplicationManager sebagai parameter ke onComplicationUpdate, yang digunakan untuk mengirim data kembali ke sistem.

Catatan: Ketika aplikasi penyedia data menyediakan data, tampilan jam akan menerima nilai mentah yang Anda kirimkan sehingga dapat mengambil informasinya.

Cuplikan kode berikut menunjukkan contoh implementasi metode onComplicationUpdate:

Kotlin

override fun onComplicationUpdate(
    complicationId: Int, dataType: Int, complicationManager: ComplicationManager) {

    Log.d(TAG, "onComplicationUpdate() id: $complicationId")

    // Used to create a unique key to use with SharedPreferences for this complication.
    val thisProvider = ComponentName(this, javaClass)

    // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
    val preferences = getSharedPreferences(ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0)

    val number = preferences.getInt(
            ComplicationTapBroadcastReceiver.getPreferenceKey(
                    thisProvider, complicationId),
                    0)
    val numberText = String.format(Locale.getDefault(), "%d!", number)

    var complicationData: ComplicationData? = null

    when (dataType) {
        ComplicationData.TYPE_SHORT_TEXT -> complicationData = ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                .setShortText(ComplicationText.plainText(numberText))
                .build()
        else -> if (Log.isLoggable(TAG, Log.WARN)) {
                    Log.w(TAG, "Unexpected complication type $dataType")
                }
    }

    if (complicationData != null) {
        complicationManager.updateComplicationData(complicationId, complicationData)
    } else {
        // If no data is sent, we still need to inform the ComplicationManager, so
        // the update job can finish and the wake lock isn't held any longer.
        complicationManager.noUpdateRequired(complicationId)
    }
}

Java

@Override
public void onComplicationUpdate(
       int complicationId, int dataType, ComplicationManager complicationManager) {

   Log.d(TAG, "onComplicationUpdate() id: " + complicationId);

   // Used to create a unique key to use with SharedPreferences for this complication.
   ComponentName thisProvider = new ComponentName(this, getClass());

   // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
   SharedPreferences preferences =
     getSharedPreferences( ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0);

   int number =
           preferences.getInt(
                   ComplicationTapBroadcastReceiver.getPreferenceKey(
                           thisProvider, complicationId),
                   0);
   String numberText = String.format(Locale.getDefault(), "%d!", number);

   ComplicationData complicationData = null;

   switch (dataType) {
       case ComplicationData.TYPE_SHORT_TEXT:
           complicationData =
                   new ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                           .setShortText(ComplicationText.plainText(numberText))
                           .build();
           break;
       default:
           if (Log.isLoggable(TAG, Log.WARN)) {
               Log.w(TAG, "Unexpected complication type " + dataType);
           }
   }

   if (complicationData != null) {
       complicationManager.updateComplicationData(complicationId, complicationData);

   } else {
       // If no data is sent, we still need to inform the ComplicationManager, so
       // the update job can finish and the wake lock isn't held any longer.
       complicationManager.noUpdateRequired(complicationId);
   }
}

Izin dan deklarasi manifes

Aplikasi penyedia data harus menyertakan deklarasi spesifik dalam manifes aplikasinya agar diperlakukan sebagai penyedia data oleh sistem Android. Bagian ini menjelaskan setelan yang diperlukan untuk aplikasi penyedia data.

Dalam manifes aplikasi Anda, deklarasikan layanan dan tambahkan filter intent tindakan permintaan update. Manifes juga harus melindungi layanan dengan menambahkan izin BIND_COMPLICATION_PROVIDER untuk memastikan bahwa hanya sistem Wear OS yang dapat terikat ke layanan penyedia.

Selain itu, sertakan atribut android:icon dalam elemen service yang menyediakan ikon putih satu warna. Sebaiknya gunakan vektor drawable untuk ikon. Ikon merepresentasikan penyedia dan ditampilkan di pemilih penyedia.

Berikut contohnya: 

<service
    android:name=".provider.IncrementingNumberComplicationProviderService"
    android:icon="@drawable/icn_complications"
    android:label="@string/complications_provider_incrementing_number"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action
         android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST"/>
    </intent-filter>
</service>

Menetapkan elemen metadata

Dalam file manifes Anda, sertakan metadata untuk menentukan jenis yang didukung, periode update, dan tindakan konfigurasi seperti yang ditunjukkan dalam contoh berikut: 

<meta-data
    android:name="android.support.wearable.complications.SUPPORTED_TYPES"
    android:value="RANGED_VALUE,SHORT_TEXT,LONG_TEXT" />

<meta-data
    android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
    android:value="300" />

Ketika penyedia data detail Anda aktif, UPDATE_PERIOD_SECONDS akan menentukan seberapa sering sistem perlu memeriksa update untuk data. Jika informasi yang ditampilkan dalam detail tidak perlu diupdate secara rutin, seperti ketika Anda menggunakan update push, tetapkan nilai ini ke 0.

Jika UPDATE_PERIOD_SECONDS tidak ditetapkan ke 0, Anda harus menggunakan nilai minimal 300 (5 menit), yaitu periode update minimal yang diberlakukan sistem, untuk menghemat masa pakai baterai di perangkat. Selain itu, perlu diingat bahwa permintaan update muncul lebih jarang ketika perangkat berada dalam mode standby atau sedang tidak dipakai.

Untuk detail selengkapnya tentang mengirim update, lihat kunci yang tercantum untuk class ComplicationProviderService dalam Referensi API Wear OS.

Menambahkan aktivitas konfigurasi

Jika diperlukan, penyedia dapat menyertakan aktivitas konfigurasi yang ditampilkan kepada pengguna ketika memilih penyedia data. Untuk menyertakan aktivitas konfigurasi, sertakan item metadata pada deklarasi layanan penyedia dalam manifes dengan kunci berikut: 

<meta-data
    android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
    android:value="PROVIDER_CONFIG_ACTION"/>

Nilainya dapat berupa tindakan apa pun.

Kemudian, buat aktivitas konfigurasi dengan filter intent untuk tindakan tersebut. Aktivitas konfigurasi harus berada dalam paket yang sama dengan penyedia. Aktivitas konfigurasi harus menampilkan RESULT_OK atau RESULT_CANCELED untuk memberi tahu sistem apakah penyedia harus ditetapkan.

Tampilan jam aman yang ditetapkan penyedia

Penyedia dapat menentukan tampilan jam tertentu sebagai "aman" untuk menerima data mereka. Ini hanya digunakan saat tampilan jam mencoba menggunakan penyedia sebagai default dan penyedia memercayai aplikasi tampilan jam.

Untuk mendeklarasikan tampilan jam berstatus aman, penyedia menambahkan metadata dengan kunci android.support.wearable.complications.SAFE_WATCH_FACES. Nilai metadata adalah daftar yang dipisahkan koma untuk nama komponen WatchFaceService, seperti jika ComponentName.flattenToString() dipanggil, atau nama paket aplikasi, dalam hal ini setiap tampilan jam dalam aplikasi yang ditetapkan akan dianggap aman. Spasi kosong dalam daftar nilai diabaikan. Contoh: 

<meta-data
       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
       android:value="
          com.app.watchface/com.app.watchface.MyWatchFaceService,
          com.anotherapp.anotherwatchface/com.something.WatchFaceService,
          com.something.text"/>

Menyediakan gambar bebas burn-in

Di layar yang rentan terhadap burn-in, blok warna solid harus dihindari dalam mode standby. Jika ikon atau gambar Anda menyertakan blok warna solid, sediakan juga versi bebas burn-in.

Jika Anda menyediakan ikon menggunakan ComplicationData.Builder#setIcon, sertakan versi aman burn-in menggunakan ComplicationData.Builder#setBurnInProtectionIcon.

Jika Anda menyediakan gambar menggunakan ComplicationData.Builder#setSmallImage, sertakan versi aman burn-in menggunakan ComplicationData.Builder#setBurnInProtectionSmallImage.

Menggunakan update push

Sebagai alternatif untuk menentukan konstanta, interval update nonzero untuk detail dalam manifes aplikasi, Anda dapat menggunakan instance ComplicationDataSourceUpdateRequester untuk meminta update secara dinamis. Untuk meminta update pada konten yang terlihat oleh pengguna detail, panggil requestUpdate().

Perhatian: Untuk menghemat masa pakai baterai perangkat, jangan panggil requestUpdate() dari instance ComplicationDataSourceUpdateRequester lebih sering daripada rata-rata 5 menit sekali.

Memberikan nilai dinamis

Mulai Wear OS 4, beberapa detail dapat menampilkan nilai yang lebih sering diperbarui berdasarkan nilai yang tersedia langsung di platform. Untuk menyediakan kemampuan ini dalam detail Anda, gunakan Kolom ComplicationData yang menerima nilai dinamis. Platform ini mengevaluasi dan sering mengupdate nilai-nilai ini, tanpa mengharuskan penyedia detail untuk berjalan.

Kolom contoh mencakup Kolom nilai dinamis GoalProgressComplicationData, dan DynamicComplicationText, yang dapat digunakan di berbagai perangkat Kolom ComplicationText. Nilai-nilai dinamis ini didasarkan pada library androidx.wear.protolayout.expression.

Dalam situasi tertentu, platform tidak dapat mengevaluasi nilai dinamis:

Menyediakan nilai-nilai yang bergantung pada waktu

Beberapa detail perlu menampilkan nilai yang berhubungan dengan waktu saat ini. Contohnya termasuk tanggal saat ini, waktu hingga pertemuan berikutnya, atau waktu di zona waktu lain.

Jangan mengupdate detail setiap detik atau menit agar nilai tersebut selalu terbaru. Sebagai gantinya, tetapkan nilai sebagai nilai yang relatif terhadap tanggal atau waktu saat ini menggunakan teks yang bergantung pada waktu. Anda dapat menggunakan builder dalam class ComplicationText untuk membuat nilai-nilai yang bergantung pada waktu ini.

Kecepatan update detail

Anda mungkin ingin mengupdate detail dengan cepat. Namun, hal ini dapat memengaruhi masa pakai baterai perangkat. Anda dapat memilih untuk menggunakan Complication request API khusus yang memungkinkan detail tertentu lebih sering diperbarui. Namun, penggunaan API ini harus diizinkan oleh produsen smartwatch. Setiap produsen smartwatch menentukan detail mana yang dapat diperbarui dengan kecepatan lebih cepat dari yang biasa diizinkan.