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

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

Permissions 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 सेट अप कर लिया हो.

मंज़ूरी दें

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

Home के एपीआई का इस्तेमाल करके ऐप्लिकेशन पब्लिश करने के लिए, Developer Console रजिस्टर करना ज़रूरी है. Home API को टेस्ट करने और इस्तेमाल करने की ज़रूरत नहीं है.

अगर कोई ऐप्लिकेशन 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. सीधे वेब पर, लिंक किए गए ऐप्लिकेशन पेज के ज़रिए.

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

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