Android पर Permissions API

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

अनुमति देने के फ़्लो की मदद से, उपयोगकर्ता बिना 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)

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

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

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

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

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

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

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

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

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

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

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