Android पर Permissions API

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

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

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

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

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

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

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

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

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 की सेटिंग वाले पेज से, ऐप्लिकेशन का ऐक्सेस वापस ले लिया है या उपयोगकर्ता के पास ज़रूरी ऐक्सेस नहीं है.

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

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

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

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

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

Developer Console registration is required to publish an app using the Home APIs. Home APIs को टेस्ट करने और उनका इस्तेमाल करने के लिए, रजिस्टर करना ज़रूरी नहीं है.

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

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

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

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

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

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

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

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

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

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

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

homeManager.requestPermissions(forceLaunch=true)

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

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

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

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

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)

उपयोगकर्ता को सहमति वाली स्क्रीन दिखेगी. यह स्क्रीन, 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 > सेटिंग > लिंक किए गए ऐप्लिकेशन वाले पेज पर जाकर. settings पर क्लिक करने पर, आपको GHA में सेटिंग वाले पेज पर ले जाया जाएगा. यहां से, लिंक किए गए ऐप्लिकेशन टाइल पर क्लिक करें. इससे आपको एक ऐसे पेज पर ले जाया जाएगा जो सहमति वाली स्क्रीन जैसा दिखता है. इस पेज से, उपयोगकर्ता ऐप्लिकेशन का ऐक्सेस हटा सकता है. उपयोगकर्ता इस पेज का इस्तेमाल करके, यह भी तय कर सकता है कि ऐप्लिकेशन, किस टाइप के डिवाइस या संवेदनशील डिवाइसों को ऐक्सेस कर सकता है.

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

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

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

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

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