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.

Lihat referensi terkait berikut:

Contoh tampilan jam dengan detail

Code lab untuk menambahkan detail ke tampilan jam

Membuat project penyedia data

Untuk membuat project di Android Studio bagi aplikasi penyedia data Anda:

Klik File > New > New project.
Di jendela Create Project Android, terima nilai default, lalu klik Next.
Di jendela Target Android Devices, pilih hanya opsi Wear, dan pada daftar versi SDK, pilih versi terbaru yang tersedia. Klik Next.
Di jendela Add an Activity to Wear, pilih Add No Activity, lalu klik Finish.
Android Studio membuat project dengan modul app untuk penyedia data Anda. Untuk informasi selengkapnya tentang project di Android Studio, lihat Membuat Project.
Mulai aplikasi penyedia data Anda dengan membuat class baru yang memperluas BroadcastReceiver. Fungsi class tersebut adalah memantau permintaan update detail dari sistem Wear OS. Selain itu, buat juga class baru yang memperluas ComplicationProviderService agar benar-benar menyediakan data seperti yang diminta oleh detail yang sesuai. Untuk informasi selengkapnya, lihat referensi berikut:
- Mengimplementasikan metode untuk permintaan update
- Class ComplicationTapBroadcastReceiver dan CustomComplicationProviderService dalam codelab berikut: Mengekspos Data ke Detail
- ComplicationToggleReceiver, LongTextProviderService, dan class lainnya dalam contoh uji coba
Catatan: Menambahkan aktivitas untuk penyedia data bersifat opsional. Misalnya, Anda mungkin ingin menambahkan aktivitas yang hanya diluncurkan ketika pengguna mengetuk suatu 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 metode ini saat data dibutuhkan dari penyedia Anda, misalnya, saat detail yang menggunakan penyedia Anda menjadi aktif, atau setelah waktu yang ditentukan berlalu. Objek ComplicationManager diteruskan sebagai parameter ke metode onComplicationUpdate, dan dapat digunakan untuk mengirim data kembali ke sistem.

Catatan: Ketika aplikasi penyedia data menyediakan data, tampilan jam akan menerima nilai mentah yang Anda kirimkan sehingga tampilan jam 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, we grab 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, 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 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, dalam elemen layanan, Anda harus menyertakan atribut android:icon. Ikon yang disediakan harus berupa ikon putih satu warna. Drawable vektor 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 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 agar masa pakai baterai perangkat lebih tahan lama. Selain itu, perlu diingat bahwa permintaan update mungkin 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 Wear API.

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

Nilai 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. Hal ini dimaksudkan untuk hanya dilakukan ketika tampilan jam mencoba menggunakan penyedia tersebut sebagai penyedia default (lihat di bawah ini), 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 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 hal ini, setiap tampilan jam dalam aplikasi yang ditetapkan akan 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 Anda menyertakan blok warna solid, Anda juga harus menyediakan 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 konstan, interval update nonzero untuk detail dalam manifes aplikasi, Anda dapat menggunakan instance ProviderUpdateRequester untuk meminta update secara dinamis. Untuk meminta update pada konten yang terlihat oleh pengguna detail, panggil onComplicationUpdate().

Perhatian: Untuk menghemat masa pakai baterai perangkat, instance ProviderUpdateRequester tidak boleh memanggil onComplicationUpdate() lebih sering daripada rata-rata 5 menit.

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 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-nilai yang bergantung pada waktu ini.