เปิดเผยข้อมูลต่อข้อมูลแทรก

แอปผู้ให้บริการข้อมูลแสดงข้อมูลบนหน้าปัด ข้อมูลแทรก ใส่ฟิลด์ที่มีข้อความ สตริง รูปภาพ และตัวเลข

การสมัครใช้บริการผู้ให้บริการข้อมูล ComplicationProviderServiceเพื่อส่งมอบเนื้อหาที่มีประโยชน์ ไปยังหน้าปัดโดยตรง

สร้างโปรเจ็กต์ผู้ให้บริการข้อมูล

วิธีสร้าง ใน Android Studio สำหรับแอปผู้ให้บริการข้อมูล ให้ทำตามขั้นตอนต่อไปนี้

1. คลิกไฟล์ > ใหม่ > โปรเจ็กต์ใหม่
2. ในหน้าต่างเทมเพลตโปรเจ็กต์ ให้คลิกแท็บ Wear OS แล้วเลือก ไม่มีกิจกรรม แล้วคลิกถัดไป
3. ในหน้าต่างกำหนดค่าโปรเจ็กต์ ให้ตั้งชื่อโปรเจ็กต์ แล้วกรอกข้อมูลใน ข้อมูลโปรเจ็กต์มาตรฐาน แล้วคลิกเสร็จสิ้น
4. Android Studio สร้างโปรเจ็กต์ที่มีโมดูลแอปสำหรับผู้ให้บริการข้อมูล สำหรับข้อมูลเพิ่มเติม ข้อมูลเกี่ยวกับโปรเจ็กต์ใน Android Studio โปรดดู สร้างโปรเจ็กต์
5. เริ่มต้นแอปผู้ให้บริการข้อมูลด้วยการสร้างคลาสใหม่ที่ขยาย BroadcastReceiver จุดประสงค์ของชั้นเรียนคือการฟัง คำขออัปเดตข้อมูลแทรกจากระบบ Wear OS นอกจากนี้ ให้สร้าง คลาสใหม่ที่ขยาย ComplicationProviderService เพื่อระบุข้อมูล ตามข้อมูลแทรกที่เหมาะสม โปรดดูข้อมูลต่อไปนี้สำหรับข้อมูลเพิ่มเติม
   • ใช้เมธอดสำหรับคำขออัปเดต
   • ComplicationTapBroadcastReceiver และ CustomComplicationProviderService คลาสใน Codelab ต่อไปนี้ การเปิดเผยข้อมูลต่อข้อมูลแทรกของหน้าปัดใน Wear OS
   • ComplicationToggleReceiver LongTextProviderService และชั้นเรียนอื่นๆ ใน ตัวอย่างชุดทดสอบ

   หมายเหตุ: การเพิ่มกิจกรรมสำหรับผู้ให้บริการข้อมูล ไม่บังคับ เช่น คุณอาจต้องการกิจกรรมที่เปิดขึ้นเมื่อผู้ใช้แตะ ข้อมูลแทรก

ใช้วิธีการสำหรับคำขออัปเดต

เมื่อต้องใช้ข้อมูลแทรก ระบบ Wear OS จะส่งคำขออัปเดตไปยังข้อมูลของคุณ คำขอได้รับ BroadcastReceiver หากต้องการตอบกลับคำขออัปเดต ผู้ให้บริการข้อมูลต้องใช้ เมธอด onComplicationUpdate() ของ ComplicationProviderService

ระบบ Wear OS จะเรียก onComplicationUpdate() เมื่อต้องการข้อมูลจาก ผู้ให้บริการ เช่น เมื่อข้อมูลแทรกเมื่อใช้ผู้ให้บริการ ทำงาน หรือเมื่อระยะเวลาผ่านไปตามที่กำหนด โดยผ่าน ComplicationManager เป็นพารามิเตอร์ให้กับ onComplicationUpdate ซึ่งใช้เพื่อส่งข้อมูลกลับไปยังระบบ

หมายเหตุ: เมื่อแอปผู้ให้บริการข้อมูลของคุณให้ข้อมูล หน้าปัดนาฬิกา ได้รับค่าดิบที่คุณส่งเพื่อให้ดึงข้อมูลได้

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการใช้งาน เมธอด 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);
   }
}

การประกาศและสิทธิ์ในไฟล์ Manifest

แอปผู้ให้บริการข้อมูลต้องมีการประกาศที่เฉพาะเจาะจงในไฟล์ Manifest ของแอปจึงถือเป็น ผู้ให้บริการข้อมูลโดยระบบ Android ส่วนนี้จะอธิบายการตั้งค่าที่จำเป็นสำหรับ แอปผู้ให้บริการข้อมูล

ประกาศบริการและเพิ่มตัวกรอง Intent การดำเนินการของคำขออัปเดตในไฟล์ Manifest ของแอป ไฟล์ Manifest ต้องปกป้องบริการด้วยการเพิ่ม BIND_COMPLICATION_PROVIDER สิทธิ์เพื่อให้มั่นใจว่ามีเพียงระบบ Wear OS เท่านั้นที่สามารถเชื่อมโยงกับบริการของผู้ให้บริการได้

นอกจากนี้ ให้ใส่แอตทริบิวต์ android:icon ใน องค์ประกอบ service ที่มีแอตทริบิวต์ ไอคอนสีเดียวสีขาว เราขอแนะนำให้ใช้เวกเตอร์ที่ถอนออกได้สำหรับไอคอน ไอคอนแสดงถึงผู้ให้บริการและแสดงในผู้ให้บริการ ตัวเลือก

ตัวอย่างเช่น

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

ระบุองค์ประกอบของข้อมูลเมตา

ในไฟล์ Manifest ให้ใส่ข้อมูลเมตาเพื่อระบุประเภทที่รองรับ ระยะเวลาการอัปเดต และการกำหนดค่าดังที่แสดงไว้ด้านล่างนี้ ตัวอย่าง:

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

เมื่อเปิดใช้ผู้ให้บริการข้อมูลแทรก UPDATE_PERIOD_SECONDS จะระบุความถี่ที่คุณต้องการให้ เพื่อตรวจสอบการอัปเดตของข้อมูล หากข้อมูลที่แสดงใน ข้อมูลแทรกไม่จำเป็นต้องอัปเดตตามกำหนดเวลาปกติ เช่น คุณใช้การอัปเดตแบบพุชอยู่ ให้ตั้งค่านี้เป็น 0

หากคุณไม่ได้ตั้งค่า UPDATE_PERIOD_SECONDS เป็น 0 คุณต้องใช้ค่าอย่างน้อย 300 (5 นาที) ซึ่งก็คือ ระยะเวลาการอัปเดตขั้นต่ำที่ระบบบังคับใช้ เพื่อคงระยะเวลา อายุการใช้งานแบตเตอรี่ของอุปกรณ์ นอกจากนี้ โปรดทราบว่าคำขออัปเดต มักน้อยลงเมื่ออุปกรณ์อยู่ในโหมดแอมเบียนท์หรือไม่ได้สวมใส่

สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการส่งการอัปเดต โปรดดูคีย์ที่แสดงอยู่สำหรับ ComplicationProviderService ในชั้นเรียน Wear OS API ข้อมูลอ้างอิง

เพิ่มกิจกรรมการกำหนดค่า

หากจำเป็น ผู้ให้บริการสามารถรวมกิจกรรมการกำหนดค่าที่ ที่ปรากฏต่อผู้ใช้เมื่อผู้ใช้เลือกผู้ให้บริการข้อมูล หากต้องการรวม กิจกรรมการกำหนดค่า ให้รวมรายการข้อมูลเมตาในบริการของผู้ให้บริการ การประกาศในไฟล์ Manifest ด้วยคีย์ต่อไปนี้

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

ค่าจะเป็นการกระทำใดก็ได้

จากนั้นสร้างกิจกรรมการกำหนดค่าด้วยตัวกรอง Intent นั้น การดำเนินการ กิจกรรมการกำหนดค่าต้องอยู่ในแพ็กเกจเดียวกับ กิจกรรมการกำหนดค่าต้องแสดงผล RESULT_OK หรือ RESULT_CANCELED เพื่อบอกระบบว่าผู้ให้บริการ ที่ควรตั้งค่า

หน้าปัดที่ปลอดภัยที่ระบุโดยผู้ให้บริการ

ผู้ให้บริการสามารถระบุหน้าปัดว่า "ปลอดภัย" เพื่อรับ ใช้เมื่อหน้าปัดพยายาม เพื่อใช้ผู้ให้บริการเป็นค่าเริ่มต้น และผู้ให้บริการก็เชื่อถือแอปหน้าปัด

ผู้ให้บริการเพิ่มข้อมูลเมตาที่มีคีย์เพื่อประกาศว่าหน้าปัดปลอดภัย android.support.wearable.complications.SAFE_WATCH_FACES ค่าข้อมูลเมตา คือรายการที่คั่นด้วยจุลภาคของ WatchFaceService ชื่อคอมโพเนนต์ กำหนดโดยเสมือน มีการเรียก ComponentName.flattenToString() หรือ ชื่อแพ็กเกจของแอป ซึ่งในกรณีนี้หน้าปัดทั้งหมดภายใน แอปที่ระบุถือว่าปลอดภัย ระบบจะละเว้นช่องว่างในรายการค่า เช่น

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

มอบรูปภาพที่ปลอดภัยแบบเบิร์นอิน

ควรหลีกเลี่ยงองค์ประกอบสีทึบบนหน้าจอที่เสี่ยงต่อการเกิดภาพค้างในหน้าจอ โหมดแอมเบียนท์ หากไอคอนหรือภาพของคุณมีบล็อกสีทึบ ยังมีเวอร์ชันที่ปลอดภัย ในตัวอีกด้วย

เมื่อคุณให้ไอคอนโดยใช้ ComplicationData.Builder#setIcon โปรดรวมเวอร์ชันที่ปลอดภัยไว้ในระบบเบิร์นอิน โดยใช้ ComplicationData.Builder#setBurnInProtectionIcon

เมื่อคุณส่งรูปภาพโดยใช้ ComplicationData.Builder#setSmallImage โปรดรวมเวอร์ชันที่ปลอดภัยไว้ในระบบเบิร์นอิน โดยใช้ ComplicationData.Builder#setBurnInProtectionSmallImage

ใช้การอัปเดตแบบพุช

นอกเหนือจากการระบุช่วงเวลาการอัปเดตคงที่ที่ไม่ใช่ศูนย์สำหรับ ข้อมูลแทรกในไฟล์ Manifest ของแอปคุณสามารถใช้อินสแตนซ์ ComplicationDataSourceUpdateRequesterเพื่อขอการอัปเดตแบบไดนามิก หากต้องการส่งคำขออัปเดตเนื้อหาที่ผู้ใช้มองเห็นของข้อมูลแทรก โปรดเรียกใช้ requestUpdate()

ข้อควรระวัง: เพื่อรักษาอายุการใช้งานแบตเตอรี่ของอุปกรณ์ อย่าเรียก requestUpdate() จากอินสแตนซ์ บ่อยกว่าทุก 5 นาทีใน ComplicationDataSourceUpdateRequester โดยเฉลี่ย

ระบุค่าแบบไดนามิก

เริ่มตั้งแต่ Wear OS 4 ข้อมูลแทรกบางอย่างจะแสดงค่าที่รีเฟรชบ่อยขึ้น โดยอิงตามมูลค่าที่มีในแพลตฟอร์มโดยตรง เพื่อทำให้ความสามารถนี้ใน ข้อมูลแทรกของคุณให้ใช้ ComplicationData ช่องที่ยอมรับ ค่าแบบไดนามิก แพลตฟอร์มจะประเมินและ อัปเดตค่าเหล่านี้เป็นประจำโดยที่ไม่ต้องเรียกใช้ผู้ให้บริการข้อมูลแทรก

ตัวอย่างช่องมีดังนี้ ช่องมูลค่าแบบไดนามิกของ GoalProgressComplicationData และ DynamicComplicationText ซึ่งใช้ใน ComplicationText มูลค่าแบบไดนามิกเหล่านี้อิงตาม คลัง androidx.wear.protolayout.expression

ในบางสถานการณ์ แพลตฟอร์มจะประเมินมูลค่าแบบไดนามิกไม่ได้ ดังนี้

• บางครั้งค่าแบบไดนามิกก็ไม่พร้อมใช้งาน: เหตุการณ์นี้อาจเกิดขึ้นได้ เช่น เมื่อพร็อพเพอร์ตี้ ไม่ได้สวมข้อมือ ในกรณีเหล่านี้ แพลตฟอร์มจะใช้มูลค่า ของ ช่องสำรองการทำให้ค่าไดนามิกไม่ถูกต้องแทนในไฟล์ ช่องตัวยึดตำแหน่งของ NoDataComplicationData
• มูลค่าแบบไดนามิกไม่พร้อมใช้งาน: เหตุการณ์นี้จะเกิดขึ้นในอุปกรณ์ที่ทำงานใน Wear OS 4 รุ่นเก่า ในสถานการณ์เช่นนี้ แพลตฟอร์มจะใช้ ช่องสำรองที่แสดงร่วมกัน เช่น getFallbackValue()

ระบุค่าที่ขึ้นอยู่กับเวลา

ข้อมูลแทรกบางอย่างจะต้องแสดงค่าที่เกี่ยวข้องกับ เช่น วันที่ปัจจุบัน เวลาก่อนถึงการประชุมครั้งต่อไป หรือเวลาในเขตเวลาอื่น

ไม่อัปเดตข้อมูลแทรกทุก วินาที หรือนาที เพื่อให้ค่าเหล่านั้นเป็นปัจจุบันอยู่เสมอ แต่ให้ระบุ ค่าที่สัมพันธ์กับวันที่หรือเวลาปัจจุบันโดยใช้ข้อความที่ขึ้นอยู่กับเวลา คุณสามารถใช้เครื่องมือสร้างใน ComplicationText เพื่อสร้างค่าที่ขึ้นอยู่กับเวลาเหล่านี้

อัตราการอัปเดตข้อมูลแทรก

คุณอาจต้องการอัปเดตข้อมูลแทรกด้วยอัตราที่รวดเร็ว แต่การดำเนินการนี้อาจส่งผลต่อแบตเตอรี่ ตลอดอายุการใช้งานอุปกรณ์ คุณสามารถเลือกใช้สิทธิ์พิเศษ API คำขอข้อมูลแทรกที่อัปเดตข้อมูลแทรกบางอย่างให้บ่อยขึ้น อย่างไรก็ตาม การใช้ API นี้จะต้อง อนุญาตโดย ผู้ผลิตนาฬิกา ผู้ผลิตนาฬิกาแต่ละรายจะเลือกข้อมูลแทรกที่จะอัปเดต เร็วกว่าที่ได้รับอนุญาต

แหล่งข้อมูลที่เกี่ยวข้อง

• ประเภทและช่อง

• ที่เก็บตัวอย่างสำหรับ Wear OS

• Codelab: การเปิดเผยข้อมูลต่อข้อมูลแทรกของหน้าปัดบน Wear OS