Commissioning API ใน Android

Commissioning API ช่วยให้แอปสามารถจัดเตรียมอุปกรณ์ได้ 2 แบบ ดังนี้

• ผ้าของคุณและผ้าของ Google
• เฉพาะผ้าของ Google เท่านั้น

วิธีคอมมิชชันอุปกรณ์ Matter

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

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

ขอให้มีการทดสอบระบบโดยตรงในแอปของคุณ

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

• สำหรับผ้าชั้นเดียว
• สำหรับผ้าหลายประเภท

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

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

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

   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")
         }
       }
   

2. สร้าง CommissioningRequest รวมถึงข้อมูลเพย์โหลดที่ได้รับ และตั้งค่าตัวเลือกเพื่อคอมมิชชันอุปกรณ์ไปยัง Google Fabric โดยใช้ setStoreToGoogleFabric:

   val commissioningRequest = CommissioningRequest.builder()
           .setOnboardingPayload(payload)
           .setStoreToGoogleFabric(true)
     // set all other options that you care about
           .build()
   

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

3. ใช้อินสแตนซ์ CommissioningClient เพื่อเริ่มการคอมมิชชัน

   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
   

4. เมื่อ CommissioningClient แสดง Intent Sender แล้ว ให้เปิด Sender ดังนี้

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

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

หากต้องการตั้งค่า Matter Fabric หลายรายการในอุปกรณ์ โปรดดูผู้ดูแลระบบหลายคนสำหรับ Commissioning API ใน Android

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

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

• สำหรับผ้าชั้นเดียว
• สำหรับผ้าหลายประเภท

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

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

หากต้องการระบุการรองรับการคอมมิชชัน 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 หากแอปของคุณไม่ใช่แอปที่แนะนำ แอปจะปรากฏในตัวเลือกเลือกแอปอื่น

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

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

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

จัดการ 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

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

ระงับการแจ้งเตือนการค้นพบที่ให้ค่าคอมมิชชัน

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

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

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

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

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

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

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

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

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

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