สร้างการ์ดการตั้งค่าด่วนที่กำหนดเองสำหรับแอป

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

แผงการตั้งค่าด่วนที่มีการ์ด VPN เปิดและปิดอยู่
รูปที่ 1 แผงการตั้งค่าด่วนที่มีการ์ด VPN เปิดและปิดอยู่

ตัดสินใจว่าจะสร้างการ์ดเมื่อใด

เราขอแนะนำให้สร้างการ์ดสำหรับฟังก์ชันการทำงานที่เฉพาะเจาะจงซึ่งคุณคาดหวังให้ผู้ใช้เข้าถึงบ่อยๆ หรือต้องการเข้าถึงอย่างรวดเร็ว (หรือทั้ง 2 อย่าง) การ์ดที่มีประสิทธิภาพมากที่สุดคือการ์ดที่มีคุณสมบัติทั้ง 2 ข้อนี้ ซึ่งช่วยให้เข้าถึงการดำเนินการที่ทำบ่อยๆ ได้อย่างรวดเร็ว

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

กรณีการใช้งานการ์ดแอปฟิตเนส
รูปที่ 2 ตัวอย่างการ์ดที่แนะนำและไม่แนะนำสำหรับแอปฟิตเนส

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

  • หลีกเลี่ยงการใช้การ์ดเพื่อเปิดแอป ให้ใช้ทางลัดของแอปหรือ Launcher มาตรฐานแทน

  • หลีกเลี่ยงการใช้การ์ดสำหรับการดำเนินการของผู้ใช้แบบครั้งเดียว โปรดใช้ทางลัดของแอปหรือการแจ้งเตือนแทน

  • หลีกเลี่ยงการสร้างการ์ดมากเกินไป เราขอแนะนำให้ใช้ไม่เกิน 2 รายการต่อแอป โดยให้ใช้ทางลัดของแอปแทน

  • หลีกเลี่ยงการใช้การ์ดที่แสดงข้อมูลแต่ผู้ใช้โต้ตอบไม่ได้ โปรดใช้การแจ้งเตือนหรือวิดเจ็ตแทน

สร้างไทล์

หากต้องการสร้างการ์ด คุณต้องสร้างไอคอนการ์ดที่เหมาะสมก่อน จากนั้นสร้างและประกาศ TileService ในไฟล์ Manifest ของแอป

ตัวอย่างการตั้งค่าด่วนแสดงตัวอย่างวิธีสร้างและจัดการการ์ด

สร้างไอคอนที่กำหนดเอง

คุณจะต้องระบุไอคอนที่กำหนดเอง ซึ่งจะแสดงบนการ์ดในแผงการตั้งค่าด่วน (คุณจะเพิ่มไอคอนนี้เมื่อประกาศ TileService ซึ่งอธิบายไว้ในส่วนถัดไป) ไอคอนต้องเป็นสีขาวทึบที่มีพื้นหลังโปร่งใส ขนาด 24 x 24dp และอยู่ในรูปแบบ VectorDrawable

ตัวอย่าง Vector Drawable
รูปที่ 3 ตัวอย่าง Vector Drawable

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

สร้างและประกาศ TileService

สร้างบริการสำหรับไทล์ที่ขยายคลาส TileService

class MyQSTileService : TileService() {

    // Called when the user adds your tile.
    override fun onTileAdded() {
        super.onTileAdded()
    }
    // Called when your app can update your tile.
    override fun onStartListening() {
        super.onStartListening()
    }

    // Called when your app can no longer update your tile.
    override fun onStopListening() {
        super.onStopListening()
    }

    // Called when the user taps on your tile in an active or inactive state.
    override fun onClick() {
        super.onClick()
    }
    // Called when the user removes your tile.
    override fun onTileRemoved() {
        super.onTileRemoved()
    }
}

ประกาศ TileService ในไฟล์ Manifest ของแอป เพิ่มชื่อและป้ายกำกับของ TileService (สูงสุด 18 อักขระสำหรับ android:label) ไอคอนที่กำหนดเองที่คุณสร้างในส่วนก่อนหน้า และสิทธิ์ที่เหมาะสม

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

จัดการ TileService

เมื่อสร้างและประกาศ TileService ในไฟล์ Manifest ของแอปแล้ว คุณต้องจัดการสถานะของแอป

TileService เป็นบริการที่มีผลผูกพัน ระบบจะเชื่อมโยง TileService เมื่อแอปของคุณส่งคำขอหรือหากระบบจำเป็นต้องสื่อสารกับแอป วงจรของบริการที่มีผลผูกพันโดยทั่วไปประกอบด้วยเมธอด Callback 4 รายการ ได้แก่ onCreate(), onBind(), onUnbind() และ onDestroy() ระบบจะเรียกใช้เมธอดเหล่านี้ทุกครั้งที่บริการเข้าสู่ระยะวงจรใหม่

ภาพรวมวงจรของ TileService

นอกเหนือจาก Callback ที่ควบคุมวงจรของบริการที่มีผลผูกพันแล้ว คุณต้องใช้เมธอดอื่นๆ ที่เจาะจงสำหรับวงจรของ TileService ด้วย ระบบอาจเรียกใช้เมธอดเหล่านี้ภายนอก onCreate() และ onDestroy() เนื่องจากระบบเรียกใช้เมธอดวงจร Service และเมธอดวงจร TileService ในเทรดแบบอะซิงโครนัส 2 เทรดที่แยกกัน

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

  • onTileAdded(): ระบบจะเรียกใช้เมธอดนี้เฉพาะเมื่อผู้ใช้เพิ่มการ์ดของคุณเป็นครั้งแรก และหากผู้ใช้นำการ์ดออกแล้วเพิ่มอีกครั้ง นี่เป็นเวลาที่ดีที่สุดในการเริ่มต้นแบบครั้งเดียว อย่างไรก็ตาม วิธีนี้อาจไม่เพียงพอสำหรับการเริ่มต้นที่จำเป็นทั้งหมด

  • onStartListening() และ onStopListening(): ระบบจะเรียกใช้เมธอดเหล่านี้ทุกครั้งที่แอปอัปเดตการ์ด และจะเรียกใช้บ่อยครั้ง TileService ยังคงเชื่อมโยงระหว่าง onStartListening() และ onStopListening() ซึ่งช่วยให้แอปแก้ไขการ์ดและพุชการอัปเดตได้

  • onTileRemoved(): ระบบจะเรียกใช้เมธอดนี้เฉพาะในกรณีที่ผู้ใช้นำการ์ดออก

เลือกโหมดการฟัง

TileService จะฟังในโหมดทำงานหรือโหมดไม่ทำงาน เราขอแนะนำให้ใช้โหมดแอ็กทีฟ ซึ่งคุณจะต้องประกาศในไฟล์ Manifest ของแอป ไม่เช่นนั้น TileService จะเป็นโหมดมาตรฐานและไม่จำเป็นต้องประกาศ

อย่าคิดว่า TileService จะอยู่นอกคู่เมธอด onStartListening() และ onStopListening()

ใช้โหมดทำงานสำหรับ TileService ที่คอยฟังและตรวจสอบสถานะของตัวเองในกระบวนการของตัวเอง TileService ในโหมดทำงานจะเชื่อมโยงกับ onTileAdded(), onTileRemoved(), เหตุการณ์การแตะ และเมื่อกระบวนการของแอปส่งคำขอ

เราขอแนะนำให้ใช้โหมดแอ็กทีฟหาก TileService ได้รับการแจ้งเตือนเมื่อควรมีการอัปเดตสถานะการ์ดโดยกระบวนการของตัวเอง การ์ดที่ใช้งานอยู่จะช่วยจำกัดภาระของระบบเนื่องจากไม่จำเป็นต้องเชื่อมโยงทุกครั้งที่แผงการตั้งค่าด่วนปรากฏต่อผู้ใช้

คุณสามารถเรียกใช้เมธอด TileService.requestListeningState() แบบคงที่เพื่อขอให้เริ่มสถานะการฟังและรับ Callback ไปยัง onStartListening() ได้

คุณประกาศโหมดแอ็กทีฟได้โดยเพิ่ม META_DATA_ACTIVE_TILE ลงในไฟล์ Manifest ของแอป

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
       android:value="true" />
    ...
</service>

โหมดไม่ได้ใช้งาน

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

แอปของคุณจะได้รับการติดต่อกลับไปยัง onStartListening() หลังจากที่ผู้ใช้เปิดแผงการตั้งค่าด่วน คุณอัปเดตออบเจ็กต์ Tile ได้กี่ครั้งก็ได้ตามต้องการระหว่างวันที่ onStartListening() ถึง onStopListening()

คุณไม่จำเป็นต้องประกาศโหมดไม่ทำงาน กล่าวคือ ไม่ต้องเพิ่ม META_DATA_ACTIVE_TILE ลงในไฟล์ Manifest ของแอป

ภาพรวมสถานะของชิ้นส่วนแผนที่

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

  • STATE_ACTIVE: บ่งบอกถึงสถานะเปิดหรือเปิดใช้ ผู้ใช้จะโต้ตอบกับไทล์ได้ขณะอยู่ในสถานะนี้

    ตัวอย่างเช่น สำหรับการ์ดแอปฟิตเนสที่ให้ผู้ใช้เริ่มเซสชันการออกกำลังกายแบบจับเวลา STATE_ACTIVE จะหมายความว่าผู้ใช้ได้เริ่มเซสชันการออกกำลังกายและตัวจับเวลากำลังทำงานอยู่

  • STATE_INACTIVE: บ่งบอกถึงสถานะปิดหรือหยุดชั่วคราว ผู้ใช้จะโต้ตอบกับไทล์ได้ขณะอยู่ในสถานะนี้

    หากใช้ตัวอย่างไทล์แอปฟิตเนสอีกครั้ง ไทล์ใน STATE_INACTIVE จะหมายความว่าผู้ใช้ยังไม่ได้เริ่มเซสชันการออกกำลังกาย แต่สามารถเริ่มได้หากต้องการ

  • STATE_UNAVAILABLE: บ่งบอกถึงสถานะไม่พร้อมใช้งานชั่วคราว ผู้ใช้จะโต้ตอบกับการ์ดของคุณไม่ได้ขณะอยู่ในสถานะนี้

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

ระบบจะตั้งค่าสถานะเริ่มต้นของออบเจ็กต์ Tile เท่านั้น คุณตั้งค่าสถานะของออบเจ็กต์ Tile ตลอดวงจรที่เหลือ

ระบบอาจปรับสีไอคอนและพื้นหลังของการ์ดเพื่อแสดงสถานะของออบเจ็กต์ Tile วัตถุ Tile รายการที่ตั้งค่าเป็น STATE_ACTIVE จะมีสีเข้มที่สุด โดย STATE_INACTIVE และ STATE_UNAVAILABLE จะสว่างขึ้นเรื่อยๆ เฉดสีที่แน่นอนจะขึ้นอยู่กับผู้ผลิตและเวอร์ชัน

การ์ด VPN มีสีเพื่อแสดงสถานะของออบเจ็กต์
รูปที่ 4 ตัวอย่างการ์ดที่เปลี่ยนสีเพื่อแสดงสถานะของการ์ด (สถานะใช้งานอยู่ ไม่ได้ใช้งาน และไม่พร้อมใช้งานตามลำดับ)

อัปเดตไทล์

คุณจะอัปเดตไทล์ได้เมื่อได้รับการติดต่อกลับที่ onStartListening() การ์ดจะอัปเดตได้อย่างน้อย 1 ครั้งจนกว่าจะได้รับการเรียกกลับไปยัง onStopListening() ทั้งนี้ขึ้นอยู่กับโหมดของการ์ด

ในโหมดทำงาน คุณจะอัปเดตไทล์ได้เพียงครั้งเดียวก่อนที่จะได้รับการติดต่อกลับที่ onStopListening() ในโหมดไม่ทำงาน คุณสามารถอัปเดตการ์ดได้บ่อยเท่าที่ต้องการระหว่างเวลา onStartListening() ถึง onStopListening()

คุณสามารถดึงข้อมูลออบเจ็กต์ Tile ได้โดยเรียกใช้ getQsTile() หากต้องการอัปเดตช่องที่เฉพาะเจาะจงของออบเจ็กต์ Tile ให้เรียกใช้เมธอดต่อไปนี้

คุณต้องเรียกใช้ updateTile() เพื่ออัปเดตการ์ดเมื่อตั้งค่าช่องของออบเจ็กต์ Tile เป็นค่าที่ถูกต้องเสร็จแล้ว ซึ่งจะทำให้ระบบแยกวิเคราะห์ข้อมูลการ์ดที่อัปเดตและอัปเดต UI

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
    super.onStartListening()
    val state = getStateFromService()
    qsTile.label = state.label
    qsTile.contentDescription = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}

การแตะแฮนเดิล

ผู้ใช้สามารถแตะการ์ดเพื่อเรียกให้แสดงการดำเนินการได้หากการ์ดอยู่ในSTATE_ACTIVEหรือSTATE_INACTIVE จากนั้นระบบจะเรียกใช้ Callback onClick() ของแอป

เมื่อแอปของคุณได้รับการเรียกกลับไปยัง onClick() แอปจะเปิดกล่องโต้ตอบหรือกิจกรรม ทริกเกอร์งานเบื้องหลัง หรือเปลี่ยนสถานะของไทล์ได้

var counter = 0
override fun onClick() {
    super.onClick()
    counter++
    qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.label = "Clicked $counter times"
    qsTile.contentDescription = qsTile.label
    qsTile.updateTile()
}

เปิดกล่องโต้ตอบ

showDialog() จะยุบแผงการตั้งค่าด่วนและแสดงกล่องโต้ตอบ ใช้กล่องโต้ตอบเพื่อเพิ่มบริบทให้กับการดำเนินการหากต้องมีการป้อนข้อมูลเพิ่มเติมหรือความยินยอมของผู้ใช้

เปิดกิจกรรม

startActivityAndCollapse() เริ่มกิจกรรมขณะยุบแผง กิจกรรมจะมีประโยชน์หากมีข้อมูลที่ละเอียดกว่าที่แสดงในกล่องโต้ตอบ หรือหากการดำเนินการของคุณมีการโต้ตอบสูง

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

การแตะการ์ดค้างไว้จะแสดงหน้าจอข้อมูลแอปให้ผู้ใช้เห็น หากต้องการลบล้างลักษณะการทำงานนี้และเปิดกิจกรรมสำหรับการตั้งค่าแทน ให้เพิ่ม <intent-filter> ลงในกิจกรรมใดกิจกรรมหนึ่งด้วย ACTION_QS_TILE_PREFERENCES

ตั้งแต่ Android API 28 เป็นต้นไป PendingIntent ต้องมี Intent.FLAG_ACTIVITY_NEW_TASK ดังนี้

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}

หรือจะเพิ่มแฟล็กใน AndroidManifest.xml ในส่วน Activity ที่เฉพาะเจาะจงก็ได้

ทำเครื่องหมายการ์ดว่าเปิด/ปิดได้

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

ตั้งค่าข้อมูลเมตา TOGGLEABLE_TILE เป็น true เพื่อทำเครื่องหมายการ์ดว่าเปิด/ปิดได้

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

ดำเนินการเฉพาะการดำเนินการที่ปลอดภัยในอุปกรณ์ที่ล็อกอย่างปลอดภัย

การ์ดอาจแสดงที่ด้านบนของหน้าจอล็อกในอุปกรณ์ที่ล็อกอยู่ หากการ์ดมีข้อมูลที่ละเอียดอ่อน ให้ตรวจสอบค่าของ isSecure() เพื่อพิจารณาว่าอุปกรณ์อยู่ในสถานะปลอดภัยหรือไม่ และ TileService ควรเปลี่ยนลักษณะการทำงานตามนั้น

หากการดำเนินการของการ์ดปลอดภัยที่จะทำขณะล็อก ให้ใช้ startActivity() เพื่อเปิดกิจกรรมที่ด้านบนของหน้าจอล็อก

หากการดำเนินการของไทล์ไม่ปลอดภัย ให้ใช้ unlockAndRun() เพื่อแจ้งให้ผู้ใช้ปลดล็อกอุปกรณ์ หากสำเร็จ ระบบจะเรียกใช้ออบเจ็กต์ Runnable ที่คุณส่งไปยังเมธอดนี้

จัดหมวดหมู่การ์ด

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

การใช้งาน

หากต้องการระบุหมวดหมู่สำหรับ TileService ให้เพิ่มช่องข้อมูลเมตาลงในการประกาศบริการในไฟล์ AndroidManifest.xml ดังนี้

  • ใน AndroidManifest.xml ให้เพิ่มองค์ประกอบ <meta-data> ภายในองค์ประกอบ <service> สำหรับ TileService
  • android:name: ตั้งค่านี้เป็น android.service.quicksettings.TILE_CATEGORY
  • android:value: กำหนดค่าคงที่ของหมวดหมู่ที่กำหนดไว้ล่วงหน้า เช่น android.service.quicksettings.CATEGORY_CONNECTIVITY หรือ android.service.quicksettings.CATEGORY_DISPLAY

ดังที่แสดงในตัวอย่างต่อไปนี้

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

API มีชุดหมวดหมู่ที่กำหนดไว้ล่วงหน้าให้เลือก หมวดหมู่เหล่านี้จะกำหนดเป็นค่าคงที่ของสตริงภายในคลาส TileService

หากไม่ได้ระบุหมวดหมู่ ระบบจะกำหนดหมวดหมู่เริ่มต้นให้โดยอัตโนมัติ ดังนี้

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

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

แจ้งให้ผู้ใช้เพิ่มการ์ดของคุณ

หากต้องการเพิ่มการ์ดด้วยตนเอง ผู้ใช้ต้องทำตามขั้นตอนต่อไปนี้

  1. ปัดลงเพื่อเปิดแผงการตั้งค่าด่วน
  2. แตะปุ่มแก้ไข
  3. เลื่อนดูการ์ดทั้งหมดในอุปกรณ์จนกว่าจะพบการ์ดของคุณ
  4. กดการ์ดค้างไว้ แล้วลากไปที่รายการการ์ดที่ใช้งานอยู่

ผู้ใช้ยังย้ายหรือนำไทล์ของคุณออกได้ทุกเมื่อ

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

ข้อความแจ้ง API สำหรับการวางการตั้งค่าด่วน
รูปที่ 5 ข้อความแจ้ง API ตำแหน่งการตั้งค่าด่วน
public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Callback จะมีข้อมูลว่ามีการเพิ่มการ์ด ไม่ได้เพิ่มการ์ด มีการ์ดอยู่แล้ว หรือมีข้อผิดพลาดเกิดขึ้นหรือไม่

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

ระบบสามารถเลือกที่จะหยุดประมวลผลคำขอสำหรับ ComponentName ที่ระบุได้หากผู้ใช้ปฏิเสธคำขอดังกล่าวหลายครั้งก่อนหน้านี้ ระบบจะระบุผู้ใช้จาก Context ที่ใช้เพื่อเรียกข้อมูลบริการนี้ ซึ่งต้องตรงกับผู้ใช้ปัจจุบัน