Commissioning API ใน Android

Commissioning API ช่วยให้แอปสามารถมอบหมายให้ดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้ได้

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

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

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

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

ขอรับค่าคอมมิชชันในแอปโดยตรง

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

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

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

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

1. เริ่มต้น ActivityResultLauncher ในกิจกรรม หากผู้ใช้ มอบหมายอุปกรณ์ในโครงสร้างพื้นฐานของ 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")
         }
       }
   

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

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

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

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

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

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

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

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

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

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

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

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

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

จัดการความตั้งใจที่เข้ามา

เมื่อเปิดใช้กิจกรรมแล้ว กิจกรรมควรตรวจสอบACTION_START_COMMISSIONING Intent ที่มีอยู่และเรียกข้อมูล Payload ดังนี้

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

หยุดการแจ้งเตือนการค้นพบที่สามารถรับค่าคอมมิชชันได้

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

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

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

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