Android पर Permissions API

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

अनुमति देने की प्रोसेस के ज़रिए, उपयोगकर्ता बिना Google Home app (GHA) का इस्तेमाल किए, स्ट्रक्चर बना सकता है. हालांकि, ऐसा तब ही किया जा सकता है, जब स्ट्रक्चर पहले से सेट अप न किया गया हो.

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() को किए गए बाद के कॉल में कोई स्ट्रक्चर नहीं मिलता है, तो इसका मतलब है कि उपयोगकर्ता ने 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}")
      }
    }
  }
}

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

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

homeManager.requestPermissions(forceLaunch=true)

स्ट्रक्चर हिंट की मदद से अनुमतियां बदलना

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

स्ट्रक्चर हिंटिंग को ConsentScreenOptions डेटा क्लास का इस्तेमाल करके मैनेज किया जाता है. ConsentScreenOptions क्लास, इन कॉन्फ़िगरेशन पैरामीटर को स्वीकार करता है:

• structureId — अनुमति वाले डायलॉग बॉक्स में पहले से चुनने के लिए, स्ट्रक्चर का खास आईडी. इसे अपडेट किए जा रहे स्ट्रक्चर के लिए, स्ट्रक्चर की प्रॉपर्टी देखकर पाएं.
• allowedStructureIds — स्ट्रक्चर आईडी की सूची. अगर यह जानकारी दी जाती है, तो अनुमति वाला डायलॉग बॉक्स, उपलब्ध स्ट्रक्चर को फ़िल्टर करेगा. इससे सिर्फ़ इस सूची में मौजूद स्ट्रक्चर दिखेंगे. ज़्यादातर मामलों में इसे तय नहीं किया जाता. हालांकि, अगर आपको यह पक्का करना है कि उपयोगकर्ता को पहले से अनुमति दी गई स्ट्रक्चर की सूची में ही रखा जाए, तो इसे तय किया जा सकता है.
• allowStructureChange — इससे यह तय होता है कि उपयोगकर्ता को पहले से चुने गए स्ट्रक्चर को बदलने की अनुमति है या नहीं. अगर ज़्यादातर मामलों में allowedStructureIds और structureId में से कम से कम एक को सेट किया गया है, तो इसे true पर सेट करें. इससे उपयोगकर्ता को सामान्य तरीके से ऐप्लिकेशन इस्तेमाल करने में मदद मिलती है.

इस ऑब्जेक्ट को requestPermissions() कॉल में वैकल्पिक पैरामीटर के तौर पर पास करें. साथ ही, forceLaunch फ़्लैग को true पर सेट करें:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forceLaunch=true, consentOptions)

उपयोगकर्ता को ऐसी स्क्रीन जहां OAuth के लिए सहमति दी जाती है दिखेगी. यह स्क्रीन, ConsentScreenOptions ऑब्जेक्ट में बताई गई स्ट्रक्चर के हिसाब से पहले ही फ़िल्टर की जा चुकी होगी.

उपयोगकर्ता को स्ट्रक्चर हिंट की मदद से स्ट्रक्चर स्विच करने की अनुमति दें

अगर किसी उपयोगकर्ता के पास ऐप्लिकेशन में एक से ज़्यादा स्ट्रक्चर हैं और आपको पहले से किसी एक स्ट्रक्चर को चुनना है, लेकिन उपयोगकर्ता को उपलब्ध स्ट्रक्चर के बीच स्विच करने की अनुमति देनी है, तो allowStructureChange फ़्लैग का इस्तेमाल करके स्ट्रक्चर में बदलाव करने की सुविधा चालू करें. साथ ही, allowStructureChange में स्ट्रक्चर की सूची दें:allowedStructureIds

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

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

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

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

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

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

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

यह देखना कि उपयोगकर्ता ने किस तरह के डिवाइसों के लिए अनुमतियां दी हैं

Google Home के नेटवर्क में, ज़्यादातर डिवाइस टाइप के लिए, उपयोगकर्ता एक बार में उस टाइप के सभी डिवाइसों के लिए अनुमतियां दे सकते हैं. संवेदनशील या पाबंदी वाले डिवाइस टाइप, जैसे कि लॉक, कैमरे या डोरबेल के लिए, उपयोगकर्ताओं को उन्हें अलग-अलग अनुमति देनी होगी.

यह पता लगाने के लिए कि किसी उपयोगकर्ता ने संवेदनशील या प्रतिबंधित डिवाइस टाइप को ऐक्सेस करने की अनुमति दी है या नहीं, स्ट्रक्चर-लेवल के consentedDeviceTypes() फ़ंक्शन का इस्तेमाल करें:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

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

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

अगर उपयोगकर्ता पूरी अनुमतियां वापस लेता है, तो उसके लिए दिशा-निर्देश

अगर उपयोगकर्ता सभी अनुमतियां रद्द कर देता है, तो मौजूदा सभी ऑटोमेशन काम करना बंद कर देंगे. इसके अलावा, अगर उपयोगकर्ता कुछ डिवाइसों का ऐक्सेस रद्द कर देता है, तो उन डिवाइसों से जुड़े स्टार्टर, शर्तें, और कार्रवाइयां काम करना बंद कर देंगी.

जब भी ऐप्लिकेशन शुरू हो, तब पक्का करें कि अनुमतियां अब भी लागू हैं. अगर उन्हें रद्द कर दिया गया है, तो पक्का करें कि पिछला सारा डेटा हटा दिया गया है. इसमें ऐप्लिकेशन में कैश किया गया डेटा भी शामिल है.