หน้านี้ได้รับการแปลโดย Cloud Translation API

Commissioning API ใน Android

Commissioning API ช่วยให้แอปสามารถมอบค่าคอมมิชชันให้กับรายการต่อไปนี้

แพลตฟอร์มของคุณและแพลตฟอร์มของ Google
เฉพาะผ้า Google เท่านั้น

วิธีจัดเตรียมอุปกรณ์ Matter

คุณเริ่มกระบวนการจัดเตรียมได้โดยทำดังนี้

ในแอปโดยตรง
ผ่านฟีเจอร์จับคู่ด่วนใน Android

ขอใบอนุญาตในแอปของคุณโดยตรง

การขออนุมัติในตัวแอปโดยตรงจะทริกเกอร์โดยปุ่มในแอป และทำได้ 2 วิธีดังนี้

สำหรับผ้าชนิดเดียว
สำหรับผ้าหลายชนิด

สำหรับผ้าผืนเดียว

วิธีขอค่าคอมมิชชัน

เริ่มต้น ActivityResultLauncher ในกิจกรรม หากผู้ใช้ได้จัดเตรียมอุปกรณ์ใน Fabric ของ Google ผลการค้นหาอาจรวมชื่อที่ผู้ใช้กำหนดให้กับอุปกรณ์ไว้เมื่อจัดเตรียม

private val commissioningLauncher =
  registerForActivityResult(StartIntentSenderForResult()) { result ->
    val resultCode = result.resultCode
    if (resultCode == RESULT_OK) {
        Log.i("CommissioningActivity", "Commissioning success")
  val deviceName =
          CommissioningResult.fromIntentSenderResult(result.resultCode, result.data).deviceName
      } else {
          Log.i("CommissioningActivity", "Commissioning failed")
      }
    }

สร้าง CommissioningRequest ซึ่งรวมถึงข้อมูลเพย์โหลดที่ได้รับ และตั้งค่าตัวเลือกเพื่อทำให้อุปกรณ์ใช้งานได้กับ Google Fabric โดยใช้ setStoreToGoogleFabric
```
val commissioningRequest = CommissioningRequest.builder()
        .setOnboardingPayload(payload)
        .setStoreToGoogleFabric(true)
  // set all other options that you care about
        .build()
```
คำเตือน: หากคุณไม่ได้ตั้งค่าเพย์โหลดที่ได้รับใน Intent โปรแกรมสแกนคิวอาร์โค้ดจะปรากฏขึ้นอีกครั้ง ซึ่งทำให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ไม่ดี

หากต้องการมอบหมายอุปกรณ์ให้กับ Fabric ของ Google และ Fabric ของคุณเอง ให้ตั้งค่าบริการการจัดเตรียมใช้งานด้วย setCommissioningService ใน CommissioningRequest

ใช้อินสแตนซ์ CommissioningClient เพื่อเริ่มการcommissioning โดยทำดังนี้

commissioningClient
  .commissionDevice(commissioningRequest)
  .addOnSuccessListener { result ->
    Log.i("CommissioningActivity", "Commissioning success")
_commissioningIntentSender.postValue(result)
      }
      .addOnFailureListener { error ->
        Log.i("CommissioningActivity", "Commissioning failed")
  }

โดยที่ _commissioningIntentSender หมายถึง

private val _commissioningIntentSender = MutableLiveData<IntentSender?>()
    val commissioningIntentSender: LiveData<IntentSender?>
    get() = _commissioningIntentSender

เมื่อ CommissioningClient ส่ง Intent Sender ให้เปิดใช้งาน Sender ดังนี้

commissioningIntentSender.observe(this) { sender ->
  if (sender != null) {
    commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build())
  }
}

สำหรับ Fabric หลายรายการ (ผู้ดูแลระบบหลายคน)

หากต้องการตั้งค่า Fabric Matter หลายรายการในอุปกรณ์ ให้ดูหัวข้อผู้ดูแลระบบหลายคนสําหรับการเริ่มต้นใช้งาน API ใน Android

จุดแรกเข้าสำหรับการจัดเตรียมใช้งาน Matter สำหรับการจับคู่ด่วนหรือการสแกนคิวอาร์โค้ด (Android เท่านั้น)

การขอการว่าจ้างด้วยวิธีจับคู่ด่วนหรือคิวอาร์โค้ดใน Android ทำได้ 2 วิธีดังนี้

สำหรับผ้าชนิดเดียว
สำหรับผ้าหลายชนิด

สำหรับผ้าผืนเดียว

ใช้ตัวกรอง Intent ACTION_START_COMMISSIONING เพื่อมอบความสามารถในการจัดเตรียมอุปกรณ์อย่างเต็มรูปแบบสําหรับแอปโดยไม่ต้องใช้ GHA เมื่อจัดเตรียม Fabric ของ Google การดำเนินการนี้รวมถึงอนุญาตให้ผู้ใช้ตั้งชื่ออุปกรณ์

ขั้นตอนการเตรียมใช้งานโดยใช้ ACTION_START_COMMISSIONING — **รูปที่ 1**: ขั้นตอนการเตรียมใช้งานโดยใช้ `ACTION_START_COMMISSIONING`

หากต้องการระบุการรองรับการสั่งงาน Fabric ของ Google ให้เพิ่ม intent-filter ต่อไปนี้ลงในประกาศกิจกรรมที่เลือกภายในไฟล์ AndroidManifest.xml

<intent-filter>
  <action android:name="com.google.android.gms.home.matter.ACTION_START_COMMISSIONING" />
  <category android:name="android.intent.category.DEFAULT" />
 </intent-filter>

intent-filter ใช้เพื่อรวมแอปของคุณไว้ในรายการแอป Matter ที่แนะนําในเครื่องมือเลือกแอปของ Commissioning API หากแอปของคุณไม่ใช่แอปที่แนะนำ แอปจะปรากฏในตัวเลือกเลือกแอปอื่น

เมื่อผู้ใช้เลือกแอปของคุณ ระบบจะเปิดแอปและนําไปยังกิจกรรมที่เลือกพร้อมACTION_START_COMMISSIONING Intent

สำหรับ Fabric หลายรายการ (ผู้ดูแลระบบหลายคน)

นอกจากนี้ คุณยังใช้ขั้นตอนการจับคู่ด่วนในสถานการณ์ที่มีผู้ดูแลระบบหลายคนได้ด้วย ดูข้อมูลเพิ่มเติมได้ที่ผู้ดูแลระบบหลายคนสําหรับ Commissioning API ใน Android

จัดการ Intent ที่เข้ามา

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

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

val payload = if (Matter.ACTION_START_COMMISSIONING.equals(intent.getAction())) {
      intent.getStringExtra(Matter.EXTRA_ONBOARDING_PAYLOAD)
    } else {
      null
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
startCommissioning(commissioningRequest)
}

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

ระงับการแจ้งเตือนการค้นพบที่มีสิทธิ์ได้รับค่าคอมมิชชัน

ตัวอย่างการแจ้งเตือนขนาดครึ่งหน้าจอของ Android — *รูปที่ 1: ตัวอย่างการแจ้งเตือนแบบครึ่งหน้าจอของ Android*

โดยค่าเริ่มต้น Google Play services ใน Android จะใช้การแจ้งเตือน "ครึ่งหน้า" ซึ่งครอบคลุมครึ่งล่างของหน้าจออุปกรณ์เคลื่อนที่เพื่อให้ผู้ใช้ทราบล่วงหน้าว่ามีอุปกรณ์ Matter ที่ให้ค่าคอมมิชชันอยู่ใกล้ๆ

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

การบล็อกที่ API นี้เปิดใช้จะหมดเวลาหากแอปของคุณอยู่เบื้องหน้านานกว่า 15 นาที หากต้องการเปิดใช้การระงับอีกครั้งหลังจากหมดเวลา ให้เรียกใช้ suppressHalfSheetNotification() อีกครั้ง ไม่เช่นนั้นการแจ้งเตือนแบบครึ่งหน้าจอจะเริ่มปรากฏขึ้น

คุณควรแชร์อุปกรณ์ Matter ใน Fabric กับ Google อย่างไร

Google ขอแนะนําอย่างยิ่งให้คุณใช้ Commissioning API เป็นช่องทางหลักในการแชร์อุปกรณ์ที่ตั้งค่าไว้ใน Fabric ของคุณเองกับ Fabric ของ Google Share API มีข้อจํากัดและควรสงวนไว้สําหรับ Use Case อื่นๆ

เหตุใดคุณจึงควรใช้ Commissioning API แทน Share API

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

หากต้องการใช้ Commissioning API คุณควรเปิดหน้าต่างการจัดเตรียมอุปกรณ์และเรียกใช้ Commissioning API ตามที่อธิบายไว้ในวิธีใช้ Commissioning API ในฐานะผู้จัดเตรียมอุปกรณ์ Matter รอง

คุณควรใช้ Share API เมื่อใด

คุณสามารถใช้ Share API เพื่อให้ผู้ใช้ปลายทางเลือกแอปพลิเคชันที่มีสิทธิ์เพื่อแชร์อุปกรณ์แบบทั่วไปกับระบบนิเวศ Matter อื่นๆ ได้