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())
    }
}

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

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

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

अगर उपयोगकर्ता ने पहले से अनुमतियां नहीं दी हैं, तो Permissions UI लॉन्च करने और नतीजे को प्रोसेस करने के लिए, 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 में रजिस्टर किया है या नहीं.

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 के लिए ब्रैंडकी पुष्टि हो गई है, तो वह पुष्टि की गई स्थिति में होगा. किसी ऐप्लिकेशन को प्रोडक्शन में लॉन्च करने के लिए, यह स्थिति ज़रूरी है:

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

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

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

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 की अनुमतियां

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

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

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

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