Android पर Commissioning API

कमीशनिंग एपीआई की मदद से, कोई ऐप्लिकेशन इन दोनों में से किसी एक को कमीशन कर सकता है:

  • आपके फ़ैब्रिक और Google के फ़ैब्रिक के बीच.
  • सिर्फ़ Google फ़ैब्रिक.

Matter डिवाइसों को चालू करने के तरीके

कमीशन पाने की प्रोसेस शुरू करने के लिए:

सीधे अपने ऐप्लिकेशन में कमीशनिंग का अनुरोध करना

ऐप्लिकेशन में सीधे तौर पर कमीशन का अनुरोध करने की सुविधा, ऐप्लिकेशन में मौजूद बटन से ट्रिगर की जा सकती है. ऐसा दो तरीकों से किया जा सकता है:

किसी एक फ़ैब्रिक के लिए

कमीशनिंग का अनुरोध करने के लिए:

  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 बनाएं. इसमें मिले पेलोड का डेटा शामिल करें. साथ ही, setStoreToGoogleFabric का इस्तेमाल करके, डिवाइस को Google फ़ैब्रिक में कमीशन करने का विकल्प सेट करें:

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

    अगर आपको डिवाइस को Google फ़ैब्रिक के साथ-साथ अपने फ़ैब्रिक से भी कमीशन करना है, तो CommissioningRequest में जाकर, कमीशन करने की सेवा को setCommissioningService पर सेट करें.

  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 से इंटेंट भेजने वाले का पता चलने के बाद, उसे लॉन्च करें:

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

एक से ज़्यादा फ़ैब्रिक के लिए (एक से ज़्यादा एडमिन)

अगर आपको किसी डिवाइस पर एक से ज़्यादा Matter फ़ैब्रिक सेट अप करने हैं, तो Android पर Commissioning API के लिए मल्टी-एडमिन लेख पढ़ें.

Matter की सुविधा वाले डिवाइस को चालू करने के लिए, Fast Pair या क्यूआर कोड स्कैन करने की सुविधा (सिर्फ़ Android के लिए)

Android डिवाइस पर, फ़ास्ट पेयर या क्यूआर कोड की मदद से कमीशनिंग का अनुरोध दो तरीकों से किया जा सकता है:

किसी एक फ़ैब्रिक के लिए

ACTION_START_COMMISSIONING इंटेंट फ़िल्टर का इस्तेमाल करें. इससे, किसी ऐप्लिकेशन को GHA की ज़रूरत नहीं पड़ेगी और वह पूरी तरह से कमीशन किया जा सकेगा. Google फ़ैब्रिक में डिवाइस को चालू करने के दौरान, उपयोगकर्ता को डिवाइस का नाम असाइन करने की अनुमति देना भी शामिल है.

ACTION_START_COMMISSIONING का इस्तेमाल करके कमीशनिंग फ़्लो
पहली इमेज: ACTION_START_COMMISSIONING का इस्तेमाल करके कमीशनिंग का फ़्लो

Google फ़ैब्रिक कमीशनिंग के लिए सहायता उपलब्ध कराने के लिए, अपनी AndroidManifest.xml फ़ाइल में चुने गए गतिविधि के एलान में यह intent-filter जोड़ें:

<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 का इस्तेमाल, Commissioning API के ऐप्लिकेशन पिकर में, सुझाए गए Matter ऐप्लिकेशन की सूची में अपना ऐप्लिकेशन शामिल करने के लिए किया जाता है. अगर आपका ऐप्लिकेशन, सुझाए गए ऐप्लिकेशन में से नहीं है, तो यह कोई दूसरा ऐप्लिकेशन चुनें विकल्प में दिखता है.

जब उपयोगकर्ता आपका ऐप्लिकेशन चुनता है, तो आपका ऐप्लिकेशन लॉन्च हो जाता है. इसके बाद, उसे चुने गए ऐक्टिविटी पर ACTION_START_COMMISSIONING इंटेंट के साथ भेज दिया जाता है.

एक से ज़्यादा फ़ैब्रिक के लिए (एक से ज़्यादा एडमिन)

एक से ज़्यादा एडमिन वाले खातों में भी FastPair फ़्लो का इस्तेमाल किया जा सकता है. ज़्यादा जानकारी के लिए, Android पर Commissioning API के लिए मल्टी-एडमिन लेख पढ़ें.

आने वाले इंटेंट को मैनेज करना

गतिविधि लॉन्च होने के बाद, उसे मौजूदा 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 पेलोड वैल्यू का मतलब यह नहीं है कि कमीशन देने की प्रोसेस को बंद कर दिया जाना चाहिए.

कमीशन पाने में मदद करने वाली सूचनाएं न दिखाएं

Android में हाफ़शीट सूचना का उदाहरण
पहली इमेज: Android पर दिखने वाली हाफ़शीट सूचना का उदाहरण

डिफ़ॉल्ट रूप से, Android पर Google Play services "हाफ़शीट" सूचनाओं का इस्तेमाल करता है. ये सूचनाएं, मोबाइल डिवाइस की स्क्रीन के निचले आधे हिस्से को कवर करती हैं. इससे लोगों को यह सूचना मिलती है कि कमीशन पाने वाले Matter डिवाइस आस-पास मौजूद हैं.

ऐप्लिकेशन के फ़ोरग्राउंड में होने पर, सूचनाएं दिखने से रोकने के लिए, suppressHalfSheetNotification() तरीके को कॉल करके, इन सूचनाओं को छिपाया जा सकता है. ज़्यादा जानकारी के लिए, एपीआई से जुड़ा दस्तावेज़ देखें.

अगर आपका ऐप्लिकेशन 15 मिनट से ज़्यादा समय तक फ़ोरग्राउंड में रहता है, तो इस एपीआई की मदद से सूचनाएं बंद करने की सुविधा बंद हो जाती है. टाइम आउट के बाद, सूचनाएं न दिखाने की सुविधा को फिर से चालू करने के लिए, suppressHalfSheetNotification() को फिर से कॉल करें. ऐसा न करने पर, हाफ़शीट सूचनाएं दिखने लगेंगी.

Google के साथ, अपने फ़ैब्रिक पर Matter डिवाइसों को कैसे शेयर किया जाना चाहिए?

Google का सुझाव है कि Commissioning API का इस्तेमाल, अपने फ़ैब्रिक पर पहले से सेट अप किए गए डिवाइस को Google फ़ैब्रिक के साथ शेयर करने के मुख्य तरीके के तौर पर करें. Share API की अपनी सीमाएं हैं. इसलिए, इसे इस्तेमाल के अन्य उदाहरणों के लिए रिज़र्व किया जाना चाहिए.

आपको Share API के बजाय Commissioning API का इस्तेमाल क्यों करना चाहिए?

कमीशनिंग एपीआई की मदद से, डिवाइस को सीधे तौर पर Google फ़ैब्रिक के साथ शेयर किया जा सकता है. यह तरीका तब बेहतर होता है, जब इसका इस्तेमाल किया जा सकता हो. Share API के ज़रिए शेयर करने पर, असली उपयोगकर्ता को ज़्यादा चरणों का पालन करना पड़ता है. उदाहरण के लिए, असली उपयोगकर्ता के डिवाइस में GHA इंस्टॉल होना चाहिए. साथ ही, उसे यह पता होना चाहिए कि प्रोसेस के दौरान GHA को कैसे चुना जाता है.

Commissioning API का इस्तेमाल करने के लिए, आपको कमीशनिंग विंडो खोलनी होगी और Commissioning API को कॉल करना होगा. इसके बारे में Matter के सेकंडरी कमिशनर के तौर पर Commissioning API का इस्तेमाल कैसे करें लेख में बताया गया है.

आपको शेयर एपीआई का इस्तेमाल कब करना चाहिए?

Share API का इस्तेमाल करके, उपयोगकर्ता को यह विकल्प दिया जा सकता है कि वह किसी डिवाइस को सामान्य तौर पर अन्य Matter नेटवर्क के साथ शेयर करने के लिए, ज़रूरी शर्तें पूरी करने वाला कोई ऐप्लिकेशन चुन सके.