Mengekspos data ke 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 informasi yang berguna ke tampilan jam secara langsung.

Membuat aplikasi penyedia data

Wear OS by Google mengirimkan permintaan update ke aplikasi penyedia data ketika perlu 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 Anda; mungkin ketika detail yang menggunakan penyedia menjadi aktif, atau ketika jumlah waktu yang ditentukan telah terlewati. Objek ComplicationManager diteruskan sebagai parameter ke metode onComplicationUpdate, dan dapat digunakan untuk mengirim data kembali ke sistem.

Catatan: Saat Anda menyediakan data sebagai penyedia data detail, tampilan jam akan menerima nilai mentah yang Anda kirimkan sehingga dapat 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 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, dalam elemen layanan, Anda harus menyertakan atribut android:icon. Ikon yang disediakan harus berupa ikon putih berwarna tunggal. Vektor yang dapat digambar direkomendasikan untuk ikon tersebut. Ikon harus mewakili penyedia dan akan ditampilkan dalam pemilih penyedia.

Berikut ini 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 jenis yang didukung, periode update, dan tindakan konfigurasi, jika diperlukan; untuk detailnya, lihat kunci yang tercantum untuk class ComplicationProviderService dalam Referensi API Wear.

Ketika penyedia data detail Anda aktif, UPDATE_PERIOD_SECONDS akan menentukan seberapa sering sistem perlu memeriksa update data. Frekuensi sebaiknya disetel selama mungkin, atau ke 0 jika update terjadwal tidak diperlukan, karena update yang terlalu sering dapat memengaruhi masa pakai baterai. Perlu diketahui bahwa permintaan update tidak dijamin akan dikirim dengan frekuensi ini. Sistem akan menerapkan periode update minimal 300 detik, dan secara khusus, permintaan update mungkin muncul lebih jarang ketika perangkat berada dalam mode standby atau tidak dipakai.

Sebagai gantinya, Anda dapat menggunakan "gaya push" untuk mengirimkan update, bukan meminta update pada jadwal yang telah ditetapkan. Gunakan ProviderUpdateRequester untuk memicu panggilan ke onComplicationUpdate sesuai kebutuhan. Contoh:

                <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 perlu, penyedia dapat menyertakan aktivitas konfigurasi yang ditampilkan kepada pengguna saat pengguna 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 yang Anda inginkan.

Kemudian, buat aktivitas konfigurasi dengan filter intent untuk tindakan tersebut. Aktivitas konfigurasi harus berada dalam paket yang sama dengan penyedia. Aktivitas konfigurasi harus menghasilkan 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. Sebaiknya hanya lakukan hal ini ketika tampilan jam mencoba menggunakan penyedia tersebut sebagai penyedia default (lihat di bawah ini), dan penyedia memercayai aplikasi tampilan jam.

Untuk mendeklarasikan tampilan jam sebagai aman, penyedia akan menambahkan metadata dengan kunci android.support.wearable.complications.SAFE_WATCH_FACES. Nilai metadata harus berupa daftar yang dipisahkan koma (spasi kosong akan diabaikan). Entri dalam daftar dapat berupa nama komponen (dari WatchFaceServices, diberikan seolah-olah ComponentName.flattenToString() telah dipanggil), atau dapat berupa nama paket (dari aplikasi, dalam situasi ketika setiap tampilan jam dalam aplikasi tertentu dianggap aman). 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 menyertakan blok warna solid, Anda juga harus menyediakan versi yang aman untuk burn-in.

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

Ketika Anda memberikan gambar menggunakan ComplicationData.Builder#setSmallImage, sertakan versi yang aman untuk 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 terkini; detail seharusnya tidak perlu diupdate sesering itu. 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 yang bergantung pada waktu ini.