خانه را در اندروید راه اندازی کنید

قبل از استفاده از هر یک از APIهای Home برای اندروید، باید home را در برنامه خود مقداردهی اولیه کنید. در این مرحله، یک نمونه تک‌لایه از Home را برای زمینه محلی ایجاد خواهید کرد.

فقط یک نمونه از Home باید در یک زمان فعال باشد.

این نقطه ورود به APIهای Home است و همچنین شامل اعلام ویژگی‌ها و انواع دستگاه‌هایی است که قصد دارید با APIهای Device & Structure و Automation استفاده کنید. اگر تازه کار با اکوسیستم Google Home را شروع کرده‌اید و مطمئن نیستید که چه ویژگی‌ها یا انواع دستگاه‌هایی را ثبت کنید، ما در این راهنما برخی از رایج‌ترین‌ها را پیشنهاد کرده‌ایم.

یک نمونه خانگی ایجاد کنید

برای شروع، این بسته‌ها را به برنامه خود وارد کنید:

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

برای مقداردهی اولیه API های Home:

1. یک ارجاع به زمینه Application context) دریافت کنید. این زمینه به هیچ چرخه حیات فعالیتی وابسته نیست و تا زمانی که برنامه شما زنده است، وجود خواهد داشت. می‌توانید آن را با فراخوانی getApplicationContext() در یک Activity یا Service دریافت کنید:

   val context = getApplicationContext()
   

2. یک نمونه FactoryRegistry با تمام ویژگی‌ها و انواع دستگاه‌هایی که قصد دارید در برنامه خود استفاده کنید، ایجاد کنید.

   در این راهنما، برخی از موارد رایج (انواع دستگاه‌های روشنایی، پریز، حسگر، کلید و ترموستات، ویژگی‌های حضور و دستیار برای اتوماسیون‌ها) را پیشنهاد کرده‌ایم، در صورتی که مطمئن نیستید به چه چیزی نیاز دارید. برای کسب اطلاعات بیشتر، به ثبت ویژگی‌ها و انواع دستگاه مراجعه کنید.

   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. در نهایت، با استفاده از context و HomeConfig ، یک نمونه تک‌لایه از Home ایجاد کنید که نقطه ورود به APIها است.

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

برای جلوگیری از خطاهای مربوط به session های نامعتبر، مهم است که فقط یک نمونه singleton از Home ایجاد شود ، که این کار با قرار دادن آن در یک اعلان شیء انجام می‌شود.

برای مثال، برنامه Sample این کار را به این صورت انجام می‌دهد:

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

ورود به سیستم گوگل از طریق برنامه

شاید بخواهید احراز هویت گوگل کاربر خود را در برنامه‌تان مدیریت کنید. انجام این کار به شما امکان می‌دهد از یک حساب کاربری در سرویس‌های مختلف گوگل مانند گوگل هوم، درایو، مپس و غیره استفاده کنید.

با ورود به سیستم گوگل از طریق برنامه، می‌توانید یک نمونه HomeClient را که صریحاً به یک کاربر خاص مرتبط است، دریافت کنید و در نتیجه، زمانی که حساب از قبل مجاز شده است، از انتخابگر حساب گوگل و صفحه رضایت عبور کنید.

علاوه بر این، این رویکرد مانع از آن می‌شود که کاربران دو صفحه انتخاب حساب کاربری مختلف را ببینند - یکی از صفحه ورود به سیستم برنامه و دیگری از صفحه اصلی گوگل.

برای انجام این کار، همان مراحل ذکر شده در ایجاد یک نمونه Home را دنبال کنید، اما به جای فراخوانی 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 را نمایش می‌دهد، جایی که کاربر می‌تواند مجوز خود را اعطا کند.

شما می‌توانید یک HomeClient با یک UserAccount ایجاد کنید و سپس requestPermissions() را با forceLaunch==true فراخوانی کنید تا دوباره صفحه رضایت‌نامه نمایش داده شود و به کاربر اجازه دهید مجوزهای اعطایی خود را به‌روزرسانی کند:

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

client.registerActivityResultCallerForPermissions(this)
client.requestPermissions(forceLaunch= true)

برای اطلاعات بیشتر در مورد مدیریت مجوزهای APIهای خانگی، به API مجوزها مراجعه کنید.

ثبت ویژگی‌ها و انواع دستگاه‌ها

کلاس FactoryRegistry به توسعه‌دهندگان کمک می‌کند تا حجم باینری برنامه خود را بهینه کنند و به آنها اجازه می‌دهد تا به صراحت مشخص کنند که کدام ویژگی‌ها و انواع دستگاه‌ها توسط برنامه آنها استفاده می‌شوند.

توجه داشته باشید که مجوزها و رجیستری کارخانه از هم جدا هستند. بنابراین، ویژگی‌ها و انواع ثبت نشده‌ای که با استفاده از مجوزها در برنامه شما در دسترس هستند اما در رجیستری کارخانه گنجانده نشده‌اند، با استفاده از API اتوماسیون غیرقابل دسترسی هستند و همچنین در فراخوانی‌های متدهای traits() یا types() بازگشت داده نمی‌شوند.