在 Android 上初始化主畫面

使用任何 Android 適用的 Home API 前，您必須在應用程式中初始化住家。在這個步驟中，您將為本機環境建立 singleton Home 執行個體。

一次只能啟用一個 Home 例項。

這是 Home API 的進入點，也涉及宣告您打算搭配 Device & Structure 和 Automation API 使用的特徵和裝置類型。如果你剛開始使用 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 執行個體，以便在應用程式中使用。

   在本指南中，我們建議使用一些常見的裝置類型 (燈具、插座、感應器、開關和溫度控制器)，以及自動化作業的在場狀態和 Google 助理特徵，以防您不確定需要哪些項目。詳情請參閱「特徵和裝置類型註冊」。

   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 的單例執行個體，這是 API 的進入點。

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

為避免無效工作階段發生錯誤，請務必只建立 Home 的單例執行個體，方法是將其包裝在 object 宣告中。

以「範例應用程式」為例，做法如下：

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、雲端硬碟、地圖等) 中使用同一個帳戶。

透過應用程式啟動的 Google 登入功能，您可以取得明確與特定使用者綁定的 HomeClient 執行個體，藉此略過 Google 帳戶挑選器和同意畫面 (如果帳戶已獲得授權)。

此外，這個方法可避免使用者看到兩個不同的帳戶選取畫面，一個來自應用程式的登入畫面，另一個來自 Google Home。

如要這麼做，請按照「建立 Home 執行個體」一文中的步驟操作，但請在步驟 4 中呼叫 Home.getClient(context, userAccount, homeConfig)，而非 Home.getClient(context, 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，然後使用 forceLaunch==true 呼叫 requestPermissions()，再次啟動同意畫面，讓使用者更新授予的權限：

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

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

如要進一步瞭解如何管理 Home API 權限，請參閱 Permissions API。

註冊特徵和裝置類型

開發人員可以透過 FactoryRegistry 類別，明確指出應用程式使用的特徵和裝置類型，藉此最佳化應用程式二進位檔大小。

請注意，權限和工廠登錄程序是分開的。因此，應用程式可透過權限存取，但未納入工廠登錄的未註冊特徵和型別，無法透過 Automation API 存取，也不會透過大量 traits() 或 types() 方法呼叫傳回。