Ekspos data untuk detail

Detail tampilan jam menampilkan data yang disediakan oleh penyedia data. Penyedia data menyediakan kolom mentah yang berisi teks, string, gambar, dan angka untuk tampilan jam.

Layanan penyedia data memperluas ComplicationProviderService untuk memberikan kepada pengguna informasi yang berguna langsung ke tampilan jam.

Membuat aplikasi penyedia data

Wear OS by Google mengirimkan permintaan update ke aplikasi penyedia data ketika ada kebutuhan untuk mengupdate data detail.

Untuk merespons permintaan update dari sistem, aplikasi penyedia data Anda harus mengimplementasikan metode onComplicationUpdate() dari class ComplicationProviderService. Metode ini akan dipanggil ketika sistem menginginkan data dari penyedia - ini bisa terjadi ketika detail yang menggunakan penyedia menjadi aktif, atau ketika jumlah waktu yang ditentukan telah terlewati. Objek ComplicationManager diberikan sebagai parameter ke metode onComplicationUpdate, dan bisa digunakan untuk mengirim data kembali ke sistem.

Catatan: Saat Anda menyediakan data sebagai penyedia data detail, tampilan jam menerima nilai mentah yang Anda kirimkan sehingga ia bisa menggambarnya pada tampilan jam.

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, we grab an incrementing number from SharedPrefs.
    val preferences = getSharedPreferences(
            ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY,
            0
    )

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

    when (dataType) {
        ComplicationData.TYPE_SHORT_TEXT ->
            ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                    .setShortText(ComplicationText.plainText(numberText))
                    .build().also { complicationData ->
                        complicationManager.updateComplicationData(complicationId, complicationData)
                    }
        else -> {
            if (Log.isLoggable(TAG, Log.WARN)) {
                Log.w(TAG, "Unexpected complication type $dataType")
            }
            // 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, we grab 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 pernyataan manifes

Aplikasi penyedia data harus menyertakan deklarasi tertentu dalam manifes aplikasi 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 aksi permintaan update. Manifes juga harus melindungi layanan dengan menambahkan izin BIND_COMPLICATION_PROVIDER untuk memastikan bahwa hanya sistem Wear OS yang bisa terikat ke layanan penyedia.

Selain itu, dalam elemen layanan, Anda harus menyertakan atribut android:icon. Ikon yang disediakan harus berupa ikon putih satu warna. Vektor dapat digambar direkomendasikan untuk ikon. Sebuah ikon harus mewakili penyedia dan akan ditampilkan di pemilih penyedia.

Inilah 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 meta data

Dalam file manifes Anda, sertakan metadata untuk menetapkan tipe yang didukung, periode update, dan aksi konfigurasi, jika diperlukan; untuk detailnya, lihat kunci yang terdaftar untuk class ComplicationProviderService di Referensi Wear API.

Ketika penyedia data detail aktif, UPDATE_PERIOD_SECONDS menetapkan seberapa sering Anda menginginkan sistem memeriksa update data. Ini sebaiknya disetel selama mungkin, atau ke 0 bila update terjadwal tidak diperlukan, karena mengupdate terlalu sering bisa memengaruhi masa pakai baterai. Perhatikan bahwa permintaan update tidak ada jaminan terkirim dengan frekuensi ini. Sistem menerapkan periode update minimum 300 detik, dan secara khusus, permintaan update mungkin muncul lebih jarang ketika perangkat dalam mode standby atau tidak dipakai.

Sebagai gantinya Anda bisa menggunakan "push style" untuk mengirim update, daripada meminta update pada jadwal yang konstan. Gunakan ProviderUpdateRequester untuk memicu panggilan ke onComplicationUpdate bila diperlukan. Misalnya:

            <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="0"/>

Menambahkan aktivitas konfigurasi

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

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

Nilainya bisa berupa aksi pilihan Anda.

Kemudian buat aktivitas konfigurasi dengan filter intent untuk aksi tersebut. Aktivitas konfigurasi harus berada dalam package yang sama dengan penyedia. Aktivitas konfigurasi harus menunjukkan RESULT_OK atau RESULT_CANCELED, untuk memberi tahu sistem bila penyedia harus disetel.

Tampilan jam aman yang ditetapkan penyedia

Penyedia bisa menetapkan tampilan jam tertentu berstatus "aman" untuk menerima data mereka. Ini sebaiknya digunakan hanya ketika tampilan jam mencoba menggunakan penyedia tersebut sebagai penyedia default (lihat di bawah), dan penyedia memercayai aplikasi tampilan jam.

Untuk menyatakan tampilan jam berstatus aman, penyedia menambahkan metadata dengan kunci android.support.wearable.complications.SAFE_WATCH_FACES. Nilai metadata harus berupa daftar yang dipisahkan koma (spasi kosong diabaikan). Entri dalam daftar bisa berupa nama komponen (dari WatchFaceServices, diberikan seolah-olah ComponentName.flattenToString() telah dipanggil), atau bisa berupa nama package (dari aplikasi, dalam hal ini, setiap tampilan jam dalam aplikasi yang ditetapkan akan dianggap aman). Misalnya:

<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

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

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

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

Menyediakan nilai-nilai yang bergantung pada waktu

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

Jangan mengupdate detail setiap detik atau menit agar nilainya selalu up to date; sebuah detail seharusnya tidak perlu mengupdate sesering itu. Sebagai gantinya, tetapkan nilai tersebut sebagai nilai relatif terhadap tanggal atau waktu saat ini menggunakan teks yang bergantung pada waktu. Anda bisa menggunakan builder dalam class ComplicationText untuk membuat nilai-nilai yang bergantung pada waktu ini.