Android पर Commissioning API

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, बनाएं. साथ ही, डिवाइस को 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 के इंटेंट सेंडर को वापस करने के बाद, सेंडर को लॉन्च करें:

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

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

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

फ़ास्ट पेयर या क्यूआर कोड स्कैन करने के लिए, Matter कमीशनिंग का एंट्री पॉइंट (सिर्फ़ Android के लिए)

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

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

किसी ऐप्लिकेशन के लिए, GHA की ज़रूरत के बिना कमीशन करने की पूरी सुविधा देने के लिए, ACTION_START_COMMISSIONING इंटेंट फ़िल्टर का इस्तेमाल करें. 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 APIs ऐप्लिकेशन पिकर में, सुझाए गए 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

null के अलावा किसी अन्य पेलोड वैल्यू से पता चलता है कि उपयोगकर्ता ने पहले ही डिवाइस का क्यूआर कोड स्कैन कर लिया है या पेयरिंग की डाल दी है. null पेलोड वैल्यू का मतलब यह नहीं है कि कमीशन करने की प्रोसेस को रद्द कर दिया जाना चाहिए.

कमीशन किए जा सकने वाले डिवाइसों की खोज की सूचनाएं बंद करना

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

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

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

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

आपको Google के साथ, अपने फ़ैब्रिक पर मौजूद Matter की सुविधा वाले डिवाइसों को कैसे शेयर करना चाहिए?

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

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

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

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

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

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