Android पर Permissions API

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

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

जारी रखने से पहले, पक्का करें कि आपने Android पर होम को चालू किया हो. यहां अनुमतियों के सभी उदाहरणों में, उस चरण के homeManager इंस्टेंस का इस्तेमाल किया गया है.

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

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

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

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

val permissionsReadyState =
homeManager.hasPermissions().collect { state ->
    when (state) {
      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")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

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

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

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

अगर उपयोगकर्ता ने पहले से अनुमतियां नहीं दी हैं, तो अनुमतियों वाला यूज़र इंटरफ़ेस (यूआई) लॉन्च करने और नतीजे को प्रोसेस करने के लिए, Home इंस्टेंस के 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}")
      }
    }
  }
}

Permissions UI को सही तरीके से लॉन्च करने के लिए, यह ज़रूरी है कि आपने अपने ऐप्लिकेशन के लिए OAuth सेट अप किया हो.

मंज़ूरी दें

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

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

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

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

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

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

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

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

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

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

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

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

इसके लिए, forceLaunch फ़्लैग को true पर सेट करके, requestPermissions() को फिर से कॉल करें:

homeManager.requestPermissions(forceLaunch=true)

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

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

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

   उपयोगकर्ता को डीप लिंक की मदद से, तीसरे पक्ष के ऐप्लिकेशन और सेवाएं वाले सब-पेज पर रीडायरेक्ट किया जा सकता है. इसके लिए, इस यूआरएल स्कीम का इस्तेमाल करें:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

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

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

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