Initialize the home on Android

Before using any of the Home APIs for Android, you must initialize the home in your app. In this step, you'll create a singleton instance of Home for the local context.

Only one instance of Home should be active at a time.

This is the entry point to the Home APIs and also involves declaring which traits and device types you intend to use with the Device & Structure and Automation APIs. If you're just starting out with the Google Home ecosystem and are not sure what traits or device types to register, we've suggested some of the most common here in this guide.

Create a Home instance

To begin, import these packages into your app:

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

To initialize the Home APIs:

Get a reference to the Application context. This context doesn't depend on any activity lifecycle, and will live as long as your app is alive. You can obtain it by calling getApplicationContext() within an Activity or Service:
```
val context = getApplicationContext()
```

Create a FactoryRegistry instance with all the traits and device types you intend to use in your app.

For this guide, we've suggested some common ones (Light, Plug, Sensor, Switch, and Thermostat device types, presence and Assistant traits for automations), in case you're not sure what you need. To learn more, see Registration of traits and device types.

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

Import statements for each individual trait and device type registered here are required (Android Studio should prompt you to add these).

Instantiate a HomeConfig using the Dispatchers.IO coroutine context and your registry instance.

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

Finally, create the singleton instance of Home, which is the entry point to the APIs, using the context and the HomeConfig.
```
val homeManager: HomeClient = Home.getClient(context, homeConfig)
```

To avoid errors with invalid sessions, it is important that only a singleton instance of Home is created, by wrapping it in an object declaration.

For an example, the Sample App does it this way:

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

App-initiated Google sign-in

You may want to manage your user's Google authentications within your app. Doing so lets you use the same user account across various Google services such as Google Home, Drive, Maps, and so forth.

With app-initiated Google sign-in, you can obtain a HomeClient instance explicitly tied to a particular user, thereby bypassing Google Account picker and consent screen when the account is already authorized.

Additionally, this approach prevents users from seeing two different account selection screens - one from the app's sign-in and one from the Google Home.

To do this, you must refer to Authenticate users with Sign in with Google and complete the following steps:

Create an OAuth web application client ID

Open the Google Cloud Console
- Navigate to the Google Cloud Console Credentials page.
- Select an existing project or create a new one.
Configure the OAuth Consent Screen (if you haven't)
- Before creating credentials, ensure the OAuth consent screen is configured with your app's details, including privacy policy and terms of service URLs.
Create an OAuth Client ID (Web Application type)
- On the Credentials page, click + CREATE CREDENTIALS and select OAuth client ID from the drop-down menu.
- For the Application type, select Web application.
- Enter a name for your web client (e.g., "My App Web Backend").
- Click Create.
Retrieve the Client ID
- After creation, the console will display your new Client ID. This is the value you will use in your Android application (e.g. "{project number}-.....apps.googleusercontent.com")
- It is recommended that you store the Client ID externally (e.g., in build.gradle) rather than hardcoding it directly

Instantiate a Google Sign-In request

Use the web app ID to create a Google sign-in request:

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

Create the Sign in with Google flow

To implement the sign-in flow, use CredentialManager to execute a Sign in with Google request. Once the user selects an account, extract their email from the resulting Google ID Token to create an android.accounts.Account. This account is then used to initialize a HomeClient instance specifically tied to that signed-in user.

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

Get a new HomeClient instance

Follow the same steps outlined in Create a Home instance, but instead of calling Home.getClient(context, homeConfig) in Step 4, call Home.getClient(context, userAccount, homeConfig), where the second parameter is a Lazy<UserAccount>. This returns an instance of HomeClientWithProvidedAccount, a subclass of HomeClient, that's explicitly tied to the specified Google Account:

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

If the specified user isn't authorized, prompt the user for their permission by calling the following methods on the HomeClientWithProvidedAccount instance:

registerActivityResultCallerForPermissions() with a reference to the ActivityResultCaller you want to use.
requestPermissions(). This brings up the GHP Consent screen, where the user can grant their permission.

You can create a HomeClient with a UserAccount and then call requestPermissions() with forceLaunch==true to launch the consent screen again to allow the user to update their permissions grant:

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

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

See Permissions API for more information on managing Home APIs permissions.

Refresh the whole activity with the new HomeClient

Once you have a new HomeClient instance, you must refresh the entire activity to resubscribe and fetch the complete structures, devices, and other pertinent data associated with this user account.

Registration of traits and device types

The FactoryRegistry class helps developers optimize their app binary size by letting them explicitly indicate which traits and device types are used by their app.

Note that permissions and the factory registry are decoupled. Therefore, unregistered traits and types that are available to your app using permissions but not included in the factory registry are inaccessible using the Automation API nor are they returned in the bulk traits() or types() method calls.

2. Set up OAuth

4. Permissions API

Initialize the home on Android Stay organized with collections Save and categorize content based on your preferences.