Android पर होम को शुरू करना

Android के लिए उपलब्ध किसी भी Home API का इस्तेमाल करने से पहले, आपको अपने ऐप्लिकेशन में होम को शुरू करना होगा. इस चरण में, आपको लोकल कॉन्टेक्स्ट के लिए, Home का सिंगलटन इंस्टेंस बनाना होगा.

एक बार में Home का सिर्फ़ एक इंस्टेंस चालू होना चाहिए.

यह Home APIs का एंट्री पॉइंट है. इसमें यह भी बताया जाता है कि आपको Device & Structure और Automation APIs के साथ, किन विशेषताओं और डिवाइस टाइप का इस्तेमाल करना है. अगर आपने Google Home नेटवर्क का इस्तेमाल करना शुरू ही किया है और आपको नहीं पता कि कौनसी सुविधाएं या डिवाइस टाइप रजिस्टर करने हैं, तो हमने इस गाइड में कुछ सबसे सामान्य सुविधाओं और डिवाइस टाइप के बारे में बताया है.

होम इंस्टेंस बनाना

शुरू करने के लिए, इन पैकेज को अपने ऐप्लिकेशन में इंपोर्ट करें:

import android.content.Context
import com.google.home.FactoryRegistry
import com.google.home.HomeConfig
import com.google.home.Home

Home API को शुरू करने के लिए:

  1. Application कॉन्टेक्स्ट का रेफ़रंस पाएं. यह कॉन्टेक्स्ट, गतिविधि पूरी होने की किसी प्रोसेस पर निर्भर नहीं करता. यह तब तक मौजूद रहेगा, जब तक आपका ऐप्लिकेशन मौजूद रहेगा. इसे पाने के लिए, Activity या Service में getApplicationContext() पर कॉल करें:

    val context = getApplicationContext()

  2. उन सभी विशेषताओं और डिवाइस टाइप के साथ FactoryRegistry का इंस्टेंस बनाएं जिनका इस्तेमाल आपको अपने ऐप्लिकेशन में करना है.

    इस गाइड में, हमने कुछ सामान्य डिवाइस टाइप (लाइट, प्लग, सेंसर, स्विच, और थर्मोस्टैट) और ऑटोमेशन के लिए, Assistant और मौजूदगी से जुड़ी कुछ सामान्य विशेषताओं के बारे में बताया है. अगर आपको नहीं पता कि आपको क्या चाहिए, तो ये आपके काम आ सकते हैं. ज़्यादा जानने के लिए, डिवाइस के टाइप और उनकी विशेषताओं का रजिस्ट्रेशन देखें.

    val registry = FactoryRegistry(
  traits = listOf(
            AirQuality,
            AreaAttendanceState,
            AreaPresenceState,
            AssistantBroadcast,
            AssistantFulfillment,
            BooleanState,
            ColorControl,
            ExtendedColorControl,
            FlowMeasurement,
            IlluminanceMeasurement,
            LevelControl,
            Notification,
            OccupancySensing,
            OnOff,
            RelativeHumidityMeasurement,
            Switch,
            TemperatureMeasurement,
            Thermostat),
  types = listOf(
            AirQualitySensorDevice,
            ColorDimmerSwitchDevice,
            ColorTemperatureLightDevice,
            ContactSensorDevice,
            DimmableLightDevice,
            DimmablePlugInUnitDevice,
            DimmerSwitchDevice,
            ExtendedColorLightDevice,
            FlowSensorDevice,
            GenericSwitchDevice,
            HumiditySensorDevice,
            LightSensorDevice,
            OccupancySensorDevice,
            OnOffLightDevice,
            OnOffLightSwitchDevice,
            OnOffPluginUnitDevice,
            OnOffSensorDevice,
            SpeakerDevice,
            TemperatureSensorDevice,
            ThermostatDevice))

    यहां रजिस्टर किए गए हर ट्रेट और डिवाइस टाइप के लिए, इंपोर्ट स्टेटमेंट ज़रूरी हैं. Android Studio आपको इन्हें जोड़ने के लिए कहेगा.

  3. Dispatchers.IO कोरोटीन कॉन्टेक्स्ट और अपनी रजिस्ट्री इंस्टेंस का इस्तेमाल करके, HomeConfig को इंस्टैंशिएट करें.

    val homeConfig = HomeConfig(
        coroutineContext = Dispatchers.IO,
        factoryRegistry = registry)

  4. आखिर में, कॉन्टेक्स्ट और HomeConfig का इस्तेमाल करके, Home का सिंगलटन इंस्टेंस बनाएं. यह एपीआई का एंट्री पॉइंट होता है.

    val homeManager: HomeClient = Home.getClient(context, homeConfig)

अमान्य सेशन की गड़बड़ियों से बचने के लिए, यह ज़रूरी है कि Home का सिर्फ़ एक सिंगलटन इंस्टेंस बनाया जाए. इसके लिए, इसे ऑब्जेक्ट डिक्लेरेशन में रैप करें.

उदाहरण के लिए, सैंपल के तौर पर मिला ऐप्लिकेशन इस तरह से काम करता है:

internal object HomeClientModule {
  @Provides
  @Singleton
  fun provideHomeClient(@ApplicationContext context: Context): HomeClient {
    return Home.getClient(
      context,
      HomeConfig(
        coroutineContext = IODispatcherModule.provideIoDispatcher(),
        factoryRegistry = registry,
      ),
    )
  }
}

ऐप्लिकेशन से शुरू किया गया Google साइन-इन

ऐसा हो सकता है कि आपको अपने ऐप्लिकेशन में, उपयोगकर्ता के Google क्रेडेंशियल मैनेज करने हों. ऐसा करने पर, Google की अलग-अलग सेवाओं के लिए एक ही उपयोगकर्ता खाते का इस्तेमाल किया जा सकता है. जैसे, Google Home, Drive, Maps वगैरह.

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

इसके अलावा, इस तरीके से उपयोगकर्ताओं को खाता चुनने के लिए दो अलग-अलग स्क्रीन नहीं दिखती हैं. इनमें से एक स्क्रीन, ऐप्लिकेशन में साइन-इन करने के लिए और दूसरी Google Home के लिए होती है.

इसके लिए, आपको 'Google से साइन इन करें' सुविधा का इस्तेमाल करके उपयोगकर्ताओं की पुष्टि करना लेख पढ़ना होगा और यह तरीका अपनाना होगा:

OAuth वेब ऐप्लिकेशन क्लाइंट आईडी बनाना

  1. Google Cloud Console खोलें
    • Google Cloud Console के क्रेडेंशियल पेज पर जाएं.
    • कोई मौजूदा प्रोजेक्ट चुनें या नया प्रोजेक्ट बनाएं.
  2. अगर आपने अब तक OAuth के लिए सहमति वाली स्क्रीन को कॉन्फ़िगर नहीं किया है, तो उसे कॉन्फ़िगर करें
    • क्रेडेंशियल बनाने से पहले, पक्का करें कि OAuth के लिए सहमति वाली स्क्रीन को आपके ऐप्लिकेशन की जानकारी के साथ कॉन्फ़िगर किया गया हो. इसमें निजता नीति और सेवा की शर्तों के यूआरएल शामिल हैं.
  3. OAuth क्लाइंट आईडी (वेब ऐप्लिकेशन टाइप) बनाना
    • क्रेडेंशियल पेज पर, + CREATE CREDENTIALS पर क्लिक करें और ड्रॉप-डाउन मेन्यू से OAuth क्लाइंट आईडी चुनें.
    • ऐप्लिकेशन टाइप के लिए, वेब ऐप्लिकेशन चुनें.
    • अपने वेब क्लाइंट के लिए कोई नाम डालें. जैसे, "My App Web Backend".
    • 'बनाएं' पर क्लिक करें.
  4. क्लाइंट आईडी वापस पाना
    • क्लाइंट आईडी बनाने के बाद, कंसोल में आपका नया क्लाइंट आईडी दिखेगा. यह वह वैल्यू है जिसका इस्तेमाल आपको अपने Android ऐप्लिकेशन में करना होगा. उदाहरण के लिए, "{project number}-.....apps.googleusercontent.com"
    • हमारा सुझाव है कि क्लाइंट आईडी को सीधे हार्डकोड करने के बजाय, उसे बाहरी तौर पर सेव करें. उदाहरण के लिए, build.gradle में

Google साइन-इन के अनुरोध को इंस्टैंशिएट करना

Google साइन-इन का अनुरोध करने के लिए, वेब ऐप्लिकेशन आईडी का इस्तेमाल करें:

// Your Google Cloud console Web Client ID for Google Sign-In
val serverClientId = BuildConfig.DEFAULT_WEB_CLIENT_ID

// Build the request for Google ID token
val googleIdOption = GetGoogleIdOption.Builder()
    .setFilterByAuthorizedAccounts(false) // Show all Google Accounts on the device
    .setServerClientId(serverClientId) // embed WebClientID in token
    .build()

// Build the GetCredentialRequest
val request = GetCredentialRequest.Builder().addCredentialOption(googleIdOption).build()

'Google से साइन इन करें' फ़्लो बनाना

साइन-इन की प्रोसेस लागू करने के लिए, CredentialManager का इस्तेमाल करके Sign in with Google अनुरोध को पूरा करें. जब उपयोगकर्ता कोई खाता चुन ले, तो android.accounts.Account बनाने के लिए, Google आईडी टोकन से उसका ईमेल पता निकालें. इसके बाद, इस खाते का इस्तेमाल करके HomeClient का एक इंस्टेंस शुरू किया जाता है. यह इंस्टेंस, साइन इन किए हुए उपयोगकर्ता से जुड़ा होता है.

  try {
    // CredentialManager is responsible for interacting with various credential providers on the device
    val credentialManager = CredentialManager.create(context)
    // Credential returns when user has selected an account and the getCredential call completes
    val result = credentialManager.getCredential(context = context, request = request)
    val credential = result.credential

    if (
      credential is CustomCredential &&
      credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL
    ) {
      try {
        val googleCredential = GoogleIdTokenCredential.createFrom(credential.data)
        googleCredential.id.let { userEmail ->
          Log.i(TAG, "Email found in Google ID Token: $email")
          /*
           Why "com.google"?
           The string "com.google" is a standard identifier used in Android's android.accounts.
           Account system to represent accounts managed by Google. This is often used when
           interacting with Android's Account Manager or when using Google-specific APIs. So,
           even if the email ends in "@gmail.com", the underlying account type or provider is
           still considered "com.google" within the Android system.
          */
          val account = Account(userEmail, "com.google")
          Log.d(TAG,"Switched account to : $userEmail")
          // Get the new Home Client Instance with the userEmail
        }
        Log.i(TAG, "Account switch complete. Emitting navigation event.")
      } catch (e: Exception) {
        Log.e(TAG,"Could not convert CustomCredential to Google ID Token", e)
      }
    }
  } catch (e: Exception) {
    Log.e(TAG, "Google Sign-In failed with unexpected error", e)
  }

नया HomeClient इंस्टेंस पाएं

होम इंस्टेंस बनाएं में बताए गए तरीके अपनाएं. हालांकि, चौथे चरण में Home.getClient(context, homeConfig) को कॉल करने के बजाय, Home.getClient(context, userAccount, homeConfig) को कॉल करें. यहां दूसरा पैरामीटर Lazy<UserAccount> है. यह HomeClientWithProvidedAccount का एक इंस्टेंस दिखाता है. यह HomeClient की एक सबक्लास है, जो साफ़ तौर पर दिए गए Google खाते से जुड़ी है:

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
         // 1. Create the Account object.
           val androidAccount = Account(userEmail,
                                        GoogleAuthUtil.GOOGLE_ACCOUNT_TYPE)
         // 2. Wrap it in UserAccount.GoogleAccount.
           UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

अगर उपयोगकर्ता के पास अनुमति नहीं है, तो HomeClientWithProvidedAccount इंस्टेंस पर ये तरीके कॉल करके, उपयोगकर्ता से अनुमति मांगें:

  1. registerActivityResultCallerForPermissions(), जिसमें उस ActivityResultCaller का रेफ़रंस हो जिसका आपको इस्तेमाल करना है.
  2. requestPermissions(). इससे GHP की सहमति वाली स्क्रीन खुलती है. यहां उपयोगकर्ता अपनी अनुमति दे सकता है.

UserAccount की मदद से HomeClient बनाया जा सकता है. इसके बाद, requestPermissions() को कॉल करें. इसमें forcePermissionFlow को ForcePermissionFlow.FORCE_LAUNCH पर सेट करें, ताकि ऐसी स्क्रीन जहां OAuth के लिए सहमति दी जाती है को फिर से लॉन्च किया जा सके. इससे उपयोगकर्ता को अपनी अनुमतियों को अपडेट करने की अनुमति मिलती है:

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
              UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

client.registerActivityResultCallerForPermissions(this)
client.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

Home API की अनुमतियों को मैनेज करने के बारे में ज़्यादा जानने के लिए, Permissions API देखें.

नए HomeClient की मदद से, पूरी गतिविधि को रीफ़्रेश करें

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

ट्रेट और डिवाइस टाइप का रजिस्ट्रेशन

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

ध्यान दें कि अनुमतियां और फ़ैक्ट्री रजिस्ट्री अलग-अलग होती हैं. इसलिए, रजिस्टर नहीं की गई ऐसी विशेषताएं और टाइप जो अनुमतियों का इस्तेमाल करके आपके ऐप्लिकेशन के लिए उपलब्ध हैं, लेकिन फ़ैक्ट्री रजिस्ट्री में शामिल नहीं हैं, उन्हें Automation API का इस्तेमाल करके ऐक्सेस नहीं किया जा सकता. साथ ही, उन्हें एक साथ कई traits() या types() कॉल में भी नहीं दिखाया जाता.

पीछे जाएं
2. OAuth सेट अप करना
आगे बढ़ें
4. Permissions API