Android पर Permissions API

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

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

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

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

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

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

अनुमतियां देखना

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

अगर जांच करने पर NOT_GRANTED या PERMISSIONS_STATE_UNAVAILABLE का PermissionsState मिलता है, तो इसका मतलब है कि उपयोगकर्ता या ऐप्लिकेशन के पास स्ट्रक्चर का ऐक्सेस नहीं है. अगर जांच करने पर GRANTED का PermissionsState मिलता है, लेकिन 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 सेट अप किया हो.

अनुमतियों की सहमति वाला यूज़र इंटरफ़ेस (यूआई), HomeClient.setLocale() के साथ कॉन्फ़िगर की गई स्थान-भाषा में रेंडर होता है. अगर इसे सेट नहीं किया गया है, तो यह ऐप्लिकेशन या डिवाइस की स्थान-भाषा के हिसाब से रेंडर होता है. किसी खास भाषा में ऐसी स्क्रीन जहां OAuth के लिए सहमति दी जाती है दिखाने के लिए, requestPermissions() को कॉल करने से पहले, अपने HomeClient इंस्टेंस पर setLocale() को कॉल करें. ज़्यादा जानकारी के लिए, ऐप्लिकेशन की भाषा कॉन्फ़िगर करना लेख पढ़ें.

मंज़ूरी दें

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

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

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

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

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

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

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

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

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

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

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

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

ऐसा करने के लिए, forcePermissionFlow को ForcePermissionFlow.FORCE_LAUNCH पर सेट करके, requestPermissions() को फिर से कॉल करें:

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

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

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

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

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

इस ऑब्जेक्ट को requestPermissions() कॉल में वैकल्पिक पैरामीटर के तौर पर पास करें. साथ ही, forcePermissionFlow को ForcePermissionFlow.FORCE_LAUNCH पर सेट करें:

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(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

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

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

अगर किसी उपयोगकर्ता के पास ऐप्लिकेशन में एक से ज़्यादा स्ट्रक्चर हैं और आपको उनमें से किसी एक को पहले से चुनना है, तो 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 खाता मिटाता है या किसी स्ट्रक्चर को छोड़ता है, तो प्लैटफ़ॉर्म बैकएंड डेटा को अपने-आप मिटा देता है:

• अगर मिटाया गया उपयोगकर्ता किसी स्ट्रक्चर का एकमात्र मालिक है, तो प्लैटफ़ॉर्म उस स्ट्रक्चर और उससे जुड़े डिवाइसों को मिटा देता है.
• अगर शेयर किए गए स्ट्रक्चर में अन्य मालिक मौजूद हैं, तो स्ट्रक्चर और उसके शेयर किए गए डिवाइस, बाकी सदस्यों के लिए उपलब्ध रहेंगे. प्लैटफ़ॉर्म, परिवार छोड़ने वाले सदस्य की सदस्यता हटा देता है. साथ ही, तीसरे पक्ष के उन सभी Cloud-to-cloud डिवाइसों को अनलिंक कर देता है जो सिर्फ़ उस सदस्य के क्रेडेंशियल से कनेक्ट किए गए थे.
• खाता मिटाने पर, उपयोगकर्ता के स्ट्रक्चर का डेटा और ऐप्लिकेशन की अनुमतियां तुरंत और हमेशा के लिए हटा दी जाती हैं. अगर उपयोगकर्ता बाद में अपना Google खाता वापस पा लेता है, तो भी उसके स्ट्रक्चर और अनुमतियां वापस नहीं मिलतीं.

Home APIs, उपयोगकर्ता के Google खाते में मौजूद डेटा को एक्सपोर्ट या मिटाने के लिए एंडपॉइंट उपलब्ध नहीं कराते हैं. Google खाते का इस्तेमाल करने वाले उपयोगकर्ताओं को Google Takeout पर जाने के लिए कहें, ताकि वे Google Home से जुड़ा अपना डेटा एक्सपोर्ट कर सकें. साथ ही, उन्हें Google खाते की सेटिंग पर जाने के लिए कहें, ताकि वे खाता मिटाने की प्रोसेस को मैनेज कर सकें.

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

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 ऐप्लिकेशन के पास हर डिवाइस का ऐक्सेस न हो. यहां दी गई टेबल में बताया गया है कि ऐसे मामलों में अनुमतियां कैसे लागू की जाती हैं.

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

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

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

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