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()
   

   หากต้องการเตรียมใช้งานอุปกรณ์ในโครงสร้างของ Google รวมถึงโครงสร้างของคุณเอง ให้ตั้งค่าบริการเตรียมใช้งานด้วย 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())
     }
   }
   

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

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

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

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

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

Google ขอแนะนำอย่างยิ่งให้คุณใช้ Commissioning API เป็นวิธีหลักในการแชร์อุปกรณ์ที่คุณตั้งค่าไว้ในโครงสร้างของคุณเองกับโครงสร้างของ 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