איך מפעילים את הבית ב-Android

לפני שמשתמשים באחד מממשקי Home API ל-Android, צריך לאתחל את הבית באפליקציה. בשלב הזה, יוצרים מופע singleton של Home עבור ההקשר המקומי.

רק מופע אחד של Home צריך להיות פעיל בכל פעם.

זוהי נקודת הכניסה לממשקי Home API, וכוללת גם הצהרה על המאפיינים וסוגי המכשירים שבהם אתם מתכוונים להשתמש עם ממשקי Device & Structure ו-Automation API. אם אתם רק מתחילים להשתמש במערכת האקולוגית של Google Home ולא בטוחים אילו תכונות או סוגי מכשירים כדאי לרשום, ריכזנו כאן כמה מהתכונות הנפוצות ביותר.

יצירת מופע של Home

כדי להתחיל, מייבאים את החבילות האלה לאפליקציה:

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

כדי לאתחל את ממשקי ה-API של Home:

1. קבלת הפניה להקשר של Application. ההקשר הזה לא תלוי במחזור חיים של פעילות כלשהי, והוא יתקיים כל עוד האפליקציה פעילה. אפשר לקבל אותו בשיחה למספר getApplicationContext() תוך Activity או Service:

   val context = getApplicationContext()
   

2. יוצרים מופע של FactoryRegistry עם כל המאפיינים וסוגי המכשירים שרוצים להשתמש בהם באפליקציה.

   במדריך הזה הצענו כמה אפשרויות נפוצות (סוגי המכשירים Light,‏ Plug,‏ Sensor,‏ Switch ו-Thermostat, תכונות הנוכחות וה-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. יוצרים מופע של HomeConfig באמצעות קורוטינה Dispatchers.IO ומופע הרישום.

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

4. לבסוף, יוצרים את מופע singleton של Home, שהוא נקודת הכניסה לממשקי ה-API, באמצעות ההקשר ו-HomeConfig.

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

כדי להימנע משגיאות שקשורות להפעלות לא תקינות, חשוב ליצור רק מופע singleton של Home, על ידי הוספתו להצהרת אובייקט.

לדוגמה, באפליקציה לדוגמה Sample App זה נעשה כך:

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, ‏ מפות Google וכו'.

כשמשתמשים בכניסה לחשבון Google שמתחילה באפליקציה, אפשר לקבל מופע של HomeClient שמקושר באופן מפורש למשתמש מסוים. כך אפשר לעקוף את בורר החשבונות של Google ואת מסך ההסכמה אם החשבון כבר קיבל הרשאה.

בנוסף, הגישה הזו מונעת מהמשתמשים לראות שני מסכים שונים לבחירת חשבון – אחד מתוך הכניסה לאפליקציה ואחד מתוך Google Home.

כדי לעשות את זה, פועלים לפי אותם השלבים שמפורטים במאמר בנושא יצירת מופע Home, אבל במקום להפעיל את Home.getClient(context, homeConfig) בשלב 4, מפעילים את 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 של Home זמין במאמר בנושא Permissions API.

רישום של מאפיינים וסוגי מכשירים

המחלקות FactoryRegistry עוזרות למפתחים לבצע אופטימיזציה של גודל הקובץ הבינארי של האפליקציה. הן מאפשרות להם לציין במפורש אילו מאפיינים וסוגי מכשירים נמצאים בשימוש באפליקציה.

שימו לב שההרשאות והרישום במפעל מופרדים. לכן, לא ניתן לגשת למאפיינים ולסוגים לא רשומים שזמינים לאפליקציה באמצעות הרשאות, אבל לא נכללים במאגר המידע של היצרן, באמצעות Automation API, והם גם לא מוחזרים בקריאות לשיטות traits() או types() בכמות גדולה.