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

API การจัดเตรียม

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

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

ระบุการรองรับการจัดเตรียม Matter

หากใช้ Google Home Mobile SDK เพื่อเรียกเก็บค่าคอมมิชชัน คุณต้องเพิ่มชื่อแพ็กเกจแอปใน Google Home Developer Console, ใช้ Matter API ของเรา และระบุว่าแอปของคุณรองรับMatterการเรียกเก็บค่าคอมมิชชันโดยจัดการ Intent ACTION_COMMISSION_DEVICE

เพิ่ม intent-filter ต่อไปนี้ในการประกาศ application ภายในไฟล์ AndroidManifest.xml

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

ดูไฟล์ Manifest ของแอปตัวอย่างของเราเพื่อใช้เป็นข้อมูลอ้างอิง

วิธีจัดเตรียมอุปกรณ์ 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 โดยใส่ข้อมูลเพย์โหลดที่ได้รับ แล้วตั้งค่าตัวเลือกเพื่อทำให้อุปกรณ์ใช้งานได้กับ Fabric ของ Google โดยใช้ 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 หลายรายการ (ผู้ดูแลระบบหลายคน)

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

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

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

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

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

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

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

หากต้องการระบุการรองรับการสั่งทําจาก Google Fabric ให้เพิ่ม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 หลายรายการ (ผู้ดูแลระบบหลายคน)

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

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

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

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ไม่ได้หมายความว่าควรยกเลิกการจัดเตรียม

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

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

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

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

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

การติดตั้งใช้งาน API นี้ดูได้ใน Google Home Sample App for Matter ดูข้อมูลเพิ่มเติมได้ที่ HalfSheetSuppressionObserver.kt

คุณควรแชร์อุปกรณ์ 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 อื่นๆ ได้

การแก้ปัญหา

ผู้ดูแลระบบหลายคน