Android पर Commissioning API

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

  • आपका फ़ैब्रिक और Google फ़ैब्रिक.
  • सिर्फ़ Google फ़ैब्रिक.

Matter को कमिशन करने के लिए सहायता उपलब्ध कराना

अगर कमीशन के लिए Google Home Mobile SDK का इस्तेमाल किया जा रहा है, तो आपको Google Home Developer Console में ऐप्लिकेशन के पैकेज का नाम जोड़ना होगा. साथ ही, हमारे Matter एपीआई लागू करने होंगे और यह बताना होगा कि आपका ऐप्लिकेशन ACTION_COMMISSION_DEVICE इंटेंट को मैनेज करके, Matter कमीशनिंग की सुविधा देता है.

अपनी AndroidManifest.xml फ़ाइल में, application एलान में यह intent-filter जोड़ें:

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

रेफ़रंस के लिए, हमारा सैंपल ऐप्लिकेशन का मेनिफ़ेस्ट देखें.

Matter डिवाइसों को कमीशन करने के तरीके

कमिशन करने की प्रोसेस शुरू की जा सकती है:

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

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

एक ही तरह के कपड़े के लिए

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

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

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

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

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

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

गतिविधि लॉन्च होने के बाद, यह मौजूदा 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 की हाफ़शीट सूचना का उदाहरण

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

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

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

इस एपीआई को लागू करने का उदाहरण, Google Home Sample App for Matter में देखा जा सकता है. ज़्यादा जानकारी के लिए, HalfSheetSuppressionObserver.kt पर जाएं.

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

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

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

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

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

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

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