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 पर कमीशनिंग एपीआई के लिए मल्टी-एडमिन देखें.

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

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

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

मल्टी-एडमिन वाले मामलों में भी फ़ास्ट पेयर की सुविधा का इस्तेमाल किया जा सकता है. ज़्यादा जानकारी के लिए, 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

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

कमीशन पाने की ज़रूरी शर्तें पूरी करने वाले वीडियो के बारे में सूचनाएं न भेजें

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

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

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

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

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

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

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

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

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

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

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