Build the Android sample app

The sample app showcases the basic capabilities of the Google Home APIs.

Prerequisites

To build, install, and test the app, you'll need to meet a few prerequisites:

  • Android Studio, version 2024.2.1 ("Ladybug") or later. Note that versions earlier than this may not work properly with the Home APIs SDK.

    Download Android Studio

  • The Android debugger (adb).

    Install adb.

    This can be done with the SDK Manager.

And to test the Home APIs, you'll need:

  • An Android device running Android 10 or later set up with a Google Account you intend to use for development. Make sure an up-to-date version of the Android Studio is installed and signed into with this development account.
  • A Wi-Fi network.
  • A Google hub that supports the Home APIs.

  • At least one supported device in the home. If this device (or any other you want to test) uses Thread, the hub must also be a Thread border router. The following device types and traits are supported by the Android sample app:

    • Color Temperature Light (on and off, brightness)
    • Contact Sensor (boolean state)
    • Dimmable Light (on and off, brightness)
    • Extended Color Light (on and off, brightness)
    • Generic Switch
    • Occupancy Sensor (occupancy sensing)
    • On/Off Light (on and off, brightness)
    • On/Off Light Switch
    • On/Off Plug-in Unit (on and off)
    • On/Off Sensor

  1. In the Google Cloud console, go to the project selector dashboard and select the project that you want to use to create OAuth credentials.
  2. Go to the APIs and Services page, and click Credentials in the navigation menu.

  3. If you haven't yet configured your consent screen for this Google Cloud project, the Configure consent screen button appears. In that case, configure your consent screen using the following procedure. Otherwise, move on to the next section.

    1. Click Configure consent screen. The OAuth consent screen page displays.
    2. Depending on your use case, select Internal or External, and then click Create. The OAuth consent screen pane displays.
    3. Enter information on the App information page according to the on-screen instructions, and then click Save and continue. The Scopes pane displays.
    4. You don't need to add any scopes, so click Save and continue. The Test users pane displays.
    5. If you want to add users to test access to your app, click Add users. The Add users pane displays. Test users have the privilege to grant permissions in your app.
    6. In the empty field, add one or more Google Account email addresses, and then click Add.
    7. Click Save and continue. The Summary pane displays.
    8. Review your OAuth consent screen information, and then click Back to dashboard.

See Setting up your OAuth consent screen on the Google Cloud Console Help site for full details.

Download the source code

The source code for the sample app is available on Github.

Navigate to where you want to save the project, then clone it:

git clone https://github.com/google-home/google-home-api-sample-app-android.git

Set up the SDK

The Home APIs in this open beta are not yet part of the standard libraries provided by Google for development. In order to develop applications with the Home APIs, you need to download and host the libraries locally.

To download the Home APIs Android SDK, you must first be signed into Google Home Developers.

Sign in now!

Build and run

  1. Open Android Studio, then open the google-home-api-sample-app-android project folder that was cloned your to local machine.
  2. During your first setup, Android Studio might take up to 10 minutes to download all the project dependencies and complete the Gradle build.
    • If you get an error during this step, such as Gradle Sync Failed, click Try Again to start the sync again.
  3. Change the package name for the sample app to a new one that hasn't been registered before, such as one based on your organization's name:
    1. Open the project.
    2. Expand the source hierarchy.
    3. Select the portion of the package you want to change - in other words, com.example.
    4. Right-click on the package and select Refactor > Rename...
    5. Click All Directories.
    6. Enter the new name and click Refactor.
    7. Edit the build.gradle.kts file, changing the android namespace and the applicationId to the new package name.
    8. Edit the AndroidManifest.xml file and change the package to the new package name wherever it occurs in the file.

  4. Generate an OAuth key by running the app in Android Studio. When you run or debug an app in Android Studio, Android Studio automatically generates an OAuth key intended for development and debugging. See Android Studio: Sign your debug build for a complete explanation.

    Connect your mobile device to your local machine. Android Studio will list your connected devices by model number. Select your device from the list, then click Run project. This builds and installs the sample app on your mobile device.

    For more detailed instructions, see Run apps on a hardware device on the Android Developers site.

    Now stop the running app.

  5. Get the OAuth certificate's SHA-1 fingerprint by following the instructions detailed in Setting up OAuth 2.0 / Native applications / Android on the Google Cloud Console Help site.

  6. Register the sample app for OAuth 2.0 and create OAuth credentials by following the instructions provided in Setting up OAuth 2.0.

    1. Indicate the application type, which is native/Android app.
    2. Add the SHA-1 fingerprint to the OAuth client by following the instructions in Setting up OAuth 2.0 / Native applications / Android on the Google Cloud Console Help site. You should generate the SHA-1 key from the default Android Studio key throughout the development process.
    3. Add test users. Test users have the privilege to grant permissions in the sample app.

  7. With your mobile device connected to your local machine, click Run project again to run the sample app on your mobile device.

Once installed, the app is available on your mobile device as Home API Sample App.