अनुमतियों का एपीआई

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

Home API, स्ट्रक्चर में मौजूद डिवाइसों को ऐक्सेस देने के लिए, OAuth 2.0 का इस्तेमाल करता है. OAuth की मदद से, उपयोगकर्ता किसी ऐप्लिकेशन या सेवा को अनुमति दे सकता है. इसके लिए, उसे अपने लॉगिन क्रेडेंशियल ज़ाहिर करने की ज़रूरत नहीं होती. Permissions API की मदद से, उपयोगकर्ता अपने Google खाते का इस्तेमाल करके, Home APIs ऐप्लिकेशन को अपने घर में मौजूद डिवाइसों का ऐक्सेस दे सकता है.

Permissions API का इस्तेमाल करने के लिए, आपको अपने ऐप्लिकेशन, Google Cloud, और Google Home Developer Console में कई चरण पूरे करने होंगे:

1. Google Cloud में OAuth सेट अप करना
   1. ऐप्लिकेशन पर हस्ताक्षर करना
   2. OAuth की सहमति वाली स्क्रीन सेट अप करना
   3. ऐप्लिकेशन रजिस्टर करना और क्रेडेंशियल बनाना
2. Permissions API को इंटिग्रेट करना
   1. अनुमतियों की जांच करना
   2. अनुमतियों का अनुरोध करना
3. अनुमतियां दें
   1. अनुमतियां बदलें
   2. अनुमतियां वापस लेना

Google Cloud में OAuth सेट अप करना

अगर आपके पास पहले से ही पुष्टि किया गया OAuth क्लाइंट है, तो नया क्लाइंट सेट अप किए बिना उस क्लाइंट का इस्तेमाल किया जा सकता है. ज़्यादा जानकारी के लिए, अगर आपके पास कोई मौजूदा OAuth क्लाइंट है लेख पढ़ें.

ऐप्लिकेशन पर हस्ताक्षर करना

1. Android Studio में ऐप्लिकेशन चलाकर, OAuth पासकोड जनरेट करें. Android Studio में किसी ऐप्लिकेशन को चलाने या डीबग करने पर, वह अपने-आप एक OAuth पासकोड जनरेट करता है. यह पासकोड, ऐप्लिकेशन को डेवलप करने और डीबग करने के लिए होता है. पूरी जानकारी के लिए, Android Studio: अपने डीबग बाइल्ड पर हस्ताक्षर करना लेख पढ़ें.

   अपने मोबाइल डिवाइस को लोकल मशीन से कनेक्ट करें. Android Studio, कनेक्ट किए गए डिवाइसों की सूची, मॉडल नंबर के हिसाब से दिखाएगा. सूची में से अपना डिवाइस चुनें. इसके बाद, प्रोजेक्ट चलाएं पर क्लिक करें. इससे सैंपल ऐप्लिकेशन बनता है और आपके मोबाइल डिवाइस पर इंस्टॉल हो जाता है.

   ज़्यादा जानकारी के लिए, Android Developers साइट पर हार्डवेयर डिवाइस पर ऐप्लिकेशन चलाना लेख पढ़ें.

   अब चल रहे ऐप्लिकेशन को बंद करें.

2. Google Cloud Console की सहायता साइट पर, OAuth 2.0 / नेटिव ऐप्लिकेशन / Android सेट अप करने के बारे में दिए गए निर्देशों का पालन करके, OAuth सर्टिफ़िकेट का SHA-1 फ़िंगरप्रिंट पाएं.

OAuth की सहमति वाली स्क्रीन सेट अप करना

1. Google Cloud Console में, प्रोजेक्ट सिलेक्टर डैशबोर्ड पर जाएं और वह प्रोजेक्ट चुनें जिसका इस्तेमाल आपको OAuth क्रेडेंशियल बनाने के लिए करना है.
2. एपीआई और सेवाएं पेज पर जाएं और नेविगेशन मेन्यू में, क्रेडेंशियल पर क्लिक करें.

3. अगर आपने अब तक इस Google Cloud प्रोजेक्ट के लिए सहमति स्क्रीन को कॉन्फ़िगर नहीं किया है, तो सहमति स्क्रीन कॉन्फ़िगर करें बटन दिखेगा. ऐसे में, यहां दिए गए तरीके का इस्तेमाल करके सहमति वाली स्क्रीन को कॉन्फ़िगर करें. अगर ऐसा नहीं है, तो अगले सेक्शन पर जाएं.

   1. सहमति वाली स्क्रीन कॉन्फ़िगर करें पर क्लिक करें. OAuth की सहमति वाली स्क्रीन वाला पेज दिखता है.
   2. इस्तेमाल के उदाहरण के आधार पर, इंटरनल या एक्सटर्नल चुनें. इसके बाद, बनाएं पर क्लिक करें. OAuth सहमति स्क्रीन पैनल दिखेगा.
   3. स्क्रीन पर दिए गए निर्देशों के मुताबिक, ऐप्लिकेशन की जानकारी वाले पेज पर जानकारी डालें. इसके बाद, सेव करें और जारी रखें पर क्लिक करें. स्कोप पैनल दिखेगा.
   4. आपको कोई स्कोप जोड़ने की ज़रूरत नहीं है. इसलिए, सेव करें और जारी रखें पर क्लिक करें. टेस्ट उपयोगकर्ता पैनल दिखता है.
   5. अगर आपको अपने ऐप्लिकेशन के ऐक्सेस की जांच करने के लिए उपयोगकर्ता जोड़ने हैं, तो उपयोगकर्ता जोड़ें पर क्लिक करें. उपयोगकर्ता जोड़ें पैनल दिखेगा. टेस्टर के पास आपके ऐप्लिकेशन में अनुमतियां देने का विशेषाधिकार होता है.
   6. खाली फ़ील्ड में, एक या उससे ज़्यादा Google खाते के ईमेल पते जोड़ें. इसके बाद, जोड़ें पर क्लिक करें.
   7. सेव करें और जारी रखें पर क्लिक करें. खास जानकारी पैनल दिखेगा.
   8. OAuth सहमति स्क्रीन की जानकारी की समीक्षा करें. इसके बाद, डैशबोर्ड पर वापस जाएं पर क्लिक करें.

पूरी जानकारी के लिए, Google Cloud Console की सहायता साइट पर OAuth की सहमति वाली स्क्रीन सेट अप करना लेख पढ़ें.

ऐप्लिकेशन रजिस्टर करना और क्रेडेंशियल बनाना

OAuth 2.0 के लिए ऐप्लिकेशन रजिस्टर करने और OAuth क्रेडेंशियल बनाने के लिए, OAuth 2.0 सेट अप करना में दिए गए निर्देशों का पालन करें. आपको ऐप्लिकेशन का टाइप बताना होगा, जो नेटिव/Android ऐप्लिकेशन है.

ऐप्लिकेशन को साइन करने से मिला SHA-1 फ़िंगरप्रिंट, Google Cloud Console पर सेट अप किए गए OAuth क्लाइंट में जोड़ें. इसके लिए, Google Cloud Console की सहायता साइट पर, OAuth 2.0 / नेटिव ऐप्लिकेशन सेट अप करना में दिए गए निर्देशों का पालन करें.

अपने मोबाइल डिवाइस को लोकल मशीन से कनेक्ट करके, सूची से अपना डिवाइस चुनें. इसके बाद, प्रोजेक्ट को चलाने के लिए प्रोजेक्ट चलाएं पर फिर से क्लिक करें. ज़्यादा जानकारी के लिए, Android Developers साइट पर हार्डवेयर डिवाइस पर ऐप्लिकेशन चलाना लेख पढ़ें.

Permissions API को इंटिग्रेट करना

किसी दिए गए स्ट्रक्चर में डिवाइसों को ऐक्सेस करने के लिए, उपयोगकर्ताओं को आपके ऐप्लिकेशन को अनुमतियां देनी होंगी. शुरू करने से पहले, पक्का करें कि आपने Home API को शुरू करने का तरीका अपनाया हो. उस चरण के homeManager इंस्टेंस का इस्तेमाल, यहां दिए गए अनुमतियों के सभी उदाहरणों में किया गया है.

सबसे पहले, SDK टूल के साथ कोई ActivityResultCaller रजिस्टर करें. उदाहरण के लिए, सैंपल ऐप्लिकेशन इसे इस तरह मैनेज करता है:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

अनुमतियों की जांच करना

हमारा सुझाव है कि अनुमतियों का अनुरोध करने से पहले, यह देख लें कि ऐप्लिकेशन के उपयोगकर्ता ने पहले ही सहमति दी है या नहीं. ऐसा करने के लिए, PermissionsState वैल्यू की Flow पाने के लिए, होम इंस्टेंस के hasPermissions() तरीके को कॉल करें:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

अगर जांच करने पर NOT_GRANTED या PERMISSIONS_STATE_UNAVAILABLE का PermissionsState दिखता है, तो आपको अनुमतियों का अनुरोध करना होगा. अगर जांच करने पर GRANTED का PermissionsState मिलता है, लेकिन structures() को बाद में कॉल करने पर कोई स्ट्रक्चर नहीं मिलता है, तो इसका मतलब है कि उपयोगकर्ता ने Google Home app (GHA) सेटिंग पेज की मदद से, ऐप्लिकेशन का ऐक्सेस रद्द कर दिया है. ऐसे में, आपको अनुमतियों का अनुरोध करना चाहिए. ऐसा न होने पर, उपयोगकर्ता के पास पहले से ही ऐक्सेस होना चाहिए.

अनुमतियों का अनुरोध करना

किसी स्ट्रक्चर में मौजूद स्ट्रक्चर और डिवाइसों को ऐक्सेस करने के लिए, आपके ऐप्लिकेशन को अनुमति देनी होगी.

अगर उपयोगकर्ता ने पहले से अनुमतियां नहीं दी हैं, तो अनुमतियों का यूज़र इंटरफ़ेस (यूआई) लॉन्च करने और नतीजे को प्रोसेस करने के लिए, होम इंस्टेंस के requestPermissions() तरीके का इस्तेमाल करें:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

अनुमतियों का यूज़र इंटरफ़ेस (यूआई) सही तरीके से लॉन्च हो, इसके लिए ज़रूरी है कि आपने अपने ऐप्लिकेशन के लिए पहले से ही OAuth सेट अप कर लिया हो.

मंज़ूरी दें

अब आपके पास अपना ऐप्लिकेशन चलाने और उपयोगकर्ता को अनुमतियां देने का विकल्प होगा. Developer Console में ऐप्लिकेशन रजिस्टर करने पर, अनुमति देने वाले उपयोगकर्ताओं का टाइप और अनुमति देने के लिए उपलब्ध डिवाइस टाइप अलग-अलग होंगे.

Home के एपीआई का इस्तेमाल करके ऐप्लिकेशन पब्लिश करने के लिए, Developer Console रजिस्टर करना ज़रूरी है. Home API को टेस्ट करने और इस्तेमाल करने की ज़रूरत नहीं है. Console में रजिस्ट्रेशन करने की सुविधा ऐक्सेस करने के लिए, अपने Google Technical Account Manager (TAM) से संपर्क करें.

अगर कोई ऐप्लिकेशन Developer Console में रजिस्टर नहीं है, तो उसकी स्थिति पुष्टि नहीं की गई के तौर पर दिखेगी. हमारा सुझाव है कि Home के एपीआई का इस्तेमाल करने से पहले, इनकी जांच करें:

• ऐप्लिकेशन के लिए अनुमतियां सिर्फ़ वे उपयोगकर्ता दे सकते हैं जो OAuth कंसोल में टेस्ट उपयोगकर्ता के तौर पर रजिस्टर हैं. पुष्टि नहीं किए गए ऐप्लिकेशन के लिए, 100 टेस्ट उपयोगकर्ताओं की सीमा तय की गई है.

• पुष्टि नहीं किए गए ऐप्लिकेशन के पास, उन सभी डिवाइसों का ऐक्सेस होगा जिन पर Home के एपीआई के लिए OAuth काम करता है. इन डिवाइसों की सूची Developer Console में दी गई है. किसी स्ट्रक्चर में मौजूद सभी डिवाइसों का ऐक्सेस दिया जाएगा.

अगर कोई ऐप्लिकेशन Developer Console में रजिस्टर है और उसे एक या उससे ज़्यादा तरह के डिवाइसों को ऐक्सेस करने की अनुमति मिली है और OAuth के लिए ब्रैंड की पुष्टि हो चुकी है, तो उसकी स्थिति पुष्टि हो चुकी है के तौर पर दिखेगी. किसी ऐप्लिकेशन को प्रोडक्शन में लॉन्च करने के लिए, यह स्टेटस ज़रूरी है:

• टेस्ट में शामिल उपयोगकर्ताओं की संख्या की सीमाएं अब लागू नहीं होंगी. कोई भी उपयोगकर्ता, ऐप्लिकेशन को अनुमति दे सकता है.
• उपयोगकर्ता सिर्फ़ उन डिवाइस टाइप को अनुमति दे सकता है जिन्हें Developer Console में अनुमति दी गई थी.

OAuth सेट अप हो जाने के बाद, ऐप्लिकेशन का requestPermissions() को कॉल करने पर, ये डायलॉग ट्रिगर होते हैं:

1. उपयोगकर्ता को वह Google खाता चुनने के लिए कहा जाता है जिसका इस्तेमाल करना है.
2. उपयोगकर्ता को उस स्ट्रक्चर को चुनने के लिए कहा जाता है जिसका ऐक्सेस उसे ऐप्लिकेशन को देना है.
   1. जिस ऐप्लिकेशन की पुष्टि नहीं हुई है उसके लिए, Home के एपीआई के साथ काम करने वाले सभी डिवाइस टाइप उपलब्ध होते हैं.
   2. पुष्टि किए गए ऐप्लिकेशन के लिए, उपयोगकर्ता सिर्फ़ उन डिवाइस टाइप को अनुमति दे सकता है जिन्हें Developer Console में मंज़ूरी मिली है.
   3. उपयोगकर्ता, संवेदनशील डिवाइस टाइप के लिए, ऐप्लिकेशन के पास मैनेज करने का ऐक्सेस है. ऐसे में, उपयोगकर्ता हर डिवाइस के हिसाब से ऐक्सेस पर पाबंदी लगा सकता है. उदाहरण के लिए, अगर किसी उपयोगकर्ता के पास तीन लॉक हैं, तो वह उनमें से सिर्फ़ एक लॉक का ऐक्सेस दे सकता है.

अनुमति मिलने के बाद, ऐप्लिकेशन Home API का इस्तेमाल करके स्ट्रक्चर में मौजूद डिवाइसों की स्थिति पढ़ सकता है और उन्हें कंट्रोल कर सकता है. अगर उपयोगकर्ता किसी खास तरह के डिवाइस या संवेदनशील डिवाइस के लिए, ऐप्लिकेशन को अनुमति नहीं देता है, तो ऐप्लिकेशन उसे ऐक्सेस करने, कंट्रोल करने या अपने-आप चालू या बंद करने के लिए, Home API का इस्तेमाल नहीं कर पाएगा.

अनुमतियां बदलें

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

ऐसा करने के लिए, forceLaunch को true पर सेट करके, requestPermissions() को फिर से कॉल करें:

homeManager.requestPermissions(forceLaunch=true)

अनुमतियां वापस लेना

उपयोगकर्ता, पहले दिए गए ऐक्सेस को रद्द कर सकते हैं:

1. Google MyAccounts पेज > डेटा और निजता > तीसरे पक्ष के ऐप्लिकेशन और सेवाएं पर जाकर. इससे, शुरुआती सहमति मिलने पर जारी किया गया OAuth टोकन रद्द हो जाएगा. साथ ही, ऐप्लिकेशन के उस किसी भी इंस्टेंस का ऐक्सेस रद्द हो जाएगा जिसका इस्तेमाल उपयोगकर्ता सभी प्लैटफ़ॉर्म (फ़ोन) और स्ट्रक्चर पर कर रहा था.

2. GHA > सेटिंग > लिंक किए गए ऐप्लिकेशन पेज पर जाकर. GHA में settings पर क्लिक करने पर, आपको सेटिंग पेज पर ले जाया जाएगा. इसके बाद, लिंक किए गए ऐप्लिकेशन टाइल पर क्लिक करें. इससे आपको एक ऐसा पेज दिखेगा जो सहमति वाली स्क्रीन से मिलता-जुलता है. इस पेज से, उपयोगकर्ता ऐप्लिकेशन का ऐक्सेस हटा सकता है. साथ ही, इस पेज का इस्तेमाल करके यह भी बदला जा सकता है कि ऐप्लिकेशन किस तरह के डिवाइसों या संवेदनशील डिवाइसों को ऐक्सेस कर सकता है.

3. सीधे वेब पर, लिंक किए गए ऐप्लिकेशन पेज के ज़रिए.

अगर आपके पास कोई मौजूदा OAuth क्लाइंट है

अगर आपके पास पब्लिश किए गए किसी ऐप्लिकेशन के लिए, पहले से ही पुष्टि किया गया OAuth क्लाइंट है, तो Home के एपीआई की जांच करने के लिए, अपने मौजूदा OAuth क्लाइंट का इस्तेमाल किया जा सकता है.

Developer Console Home के एपीआई को टेस्ट करने और इस्तेमाल करने के लिए, रजिस्टर करने की ज़रूरत नहीं है. हालांकि, ऐप्लिकेशन पब्लिश करने के लिए, आपको अब भी मंज़ूरी पा चुके Developer Console रजिस्ट्रेशन की ज़रूरत होगी. भले ही, आपके पास किसी दूसरे इंटिग्रेशन से पुष्टि किया गया OAuth क्लाइंट हो.

इन बातों का ध्यान रखें:

• किसी मौजूदा OAuth क्लाइंट का इस्तेमाल करते समय, 100 उपयोगकर्ताओं की सीमा होती है. टेस्ट उपयोगकर्ताओं को जोड़ने के बारे में जानने के लिए, OAuth की सहमति वाली स्क्रीन सेट अप करना लेख पढ़ें. OAuth की पुष्टि के अलावा, Home के एपीआई की ओर से यह तय किया गया है कि आपके ऐप्लिकेशन को अनुमतियां देने वाले उपयोगकर्ताओं की संख्या 100 से ज़्यादा नहीं होनी चाहिए. Developer Console रजिस्टर करने के बाद, यह पाबंदी हट जाती है.

• जब आप अपने ऐप्लिकेशन को Home के एपीआई के साथ अपडेट करने के लिए तैयार हों, तबDeveloper Console रजिस्ट्रेशन को अनुमति के लिए भेजा जाना चाहिए. ऐसा तब किया जाना चाहिए, जब आप OAuth के ज़रिए डिवाइस टाइप के अनुदान पर पाबंदी लगाने के लिए तैयार हों.

जिन Google Cloud ऐप्लिकेशन की OAuth पुष्टि अब भी बाकी है उनके लिए, उपयोगकर्ता OAuth फ़्लो तब तक पूरा नहीं कर सकते, जब तक पुष्टि पूरी नहीं हो जाती. अनुमतियां देने की कोशिश करने पर, यह गड़बड़ी दिखेगी:

Access blocked: <Project Name> has not completed the Google verification process.

OkGoogle की अनुमतियां

okGoogle कमांड, स्ट्रक्चर-लेवल का कमांड है. इसका इस्तेमाल, स्ट्रक्चर में मौजूद किसी भी डिवाइस को ऑटोमेट करने के लिए किया जा सकता है. हालांकि, हो सकता है कि Home APIs ऐप्लिकेशन के पास हर डिवाइस का ऐक्सेस न हो. नीचे दी गई टेबल में बताया गया है कि ऐसे मामलों में अनुमतियां कैसे लागू की जाती हैं.