The Sample App showcases the basic capabilities of the Google Home APIs for Android.

## 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](https://developer.android.com/studio)
- The Android debugger (`adb`).

  Install[`adb`](https://developer.android.com/studio/command-line/adb).

  This can be done with the[SDK Manager](https://developer.android.com/studio/intro/update#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 theAndroid Studiois installed and signed into with this development account.
- A Wi-Fi network.
- To access and controlMatterdevices, you also need a[Google hub that supports the Home APIs](https://developers.home.google.com/apis/android/sdk#supported_hubs). See[Connectivity on Android](https://developers.home.google.com/apis/android/connectivity)for details.
- 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:

  <br />

  - 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
  - Google Camera
  - 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

  <br />

## Download the source code

The[source code](https://github.com/google-home/google-home-api-sample-app-android)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 for Android in this open beta are not yet part of the standard libraries provided by Google for development. In order to develop Android 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!](https://developers.home.google.com/_d/signin?continue=https://developers.home.google.com/apis/android/sample-app/build&prompt=select_account)

## Build the app

1. OpenAndroid 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 Studiomight take up to 10 minutes to download all the project dependencies and complete the Gradle build.

   | **Tip:** If you get an error during this step, such as`Gradle Sync Failed`, click**Try Again**to start the sync again.
3. Connect your computer to a physical Android phone through a USB cable and enable ADB in the[developer options](https://developer.android.com/tools/adb#Enabling). Make sureAndroid Studiocan connect to the Android phone through ADB.

   | **Note:** We recommend you run the Sample App on a real Android phone instead of the Android emulator since the Home APIs rely on the Google Play services running on a real phone.
4. 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...** ![Refactor > Rename menu](https://developers.home.google.com/static/apis/images/Android-Studio-Refactor-Rename.png)
   5. Enter the new name and click**Refactor**.
   6. Edit the`build.gradle.kts`file, changing the`android namespace`and the`applicationId`to the new package name.
5. After all the required libraries are downloaded and the Gradle synchronization is complete, click the**Run**button to build and run the app. When the app is running successfully on your phone, you'll see the Sample App main page.

### Create a signing certificate

When you run or debug an app inAndroid Studio, it automatically generates a debug certificate intended for development and debugging. See[Android Studio: Sign your debug build](https://developer.android.com/studio/publish/app-signing#debug-mode)for a complete explanation.

1. Generate a debug app signing certificate by running the app inAndroid Studio. When you run or debug an app inAndroid Studio,Android Studioautomatically generates an app signing certificate intended for development and debugging. See[Android Studio: Sign your debug build](https://developer.android.com/studio/publish/app-signing#debug-mode)for a complete explanation.

   Connect your mobile device to your local machine.Android Studiowill 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](https://developer.android.com/studio/run/device)on the Android Developers site.

   Now stop the running app.
2. Get your debug certificate's SHA-1 fingerprint by following the instructions detailed in[Manage OAuth Clients / Application Types / Native applications / Android](https://support.google.com/cloud/answer/15549257#zippy=%2Cstep-create-a-new-client-secret%2Cstep-configure-your-app-to-use-the-new-secret%2Cnative-applications-android-ios-desktop-uwp-chrome-extensions-tv-and-limited-input%2Candroid:%7E:text=input%20device%20flow.-,Android,-Note%3A%20Currently%2C%20obtaining)on the Google Cloud Console Help site.

   <br />

   | **Tip:** To determine the location of your project's keystore in either Android Studio 2024.2.1 ('Ladybug') or later:
   | 1. In**Settings** \>**Experimental** , make sure**Configure all Gradle tasks during Gradle Sync**is selected.
   | 2. Open the Gradle Tool Window.
   | 3. Select your project.
   | 4. Expand the Gradle settings tree starting from**app** (**app** \>**tasks** \>**android**).
   | 5. Under**android** , select**signingReport** .  
   |    ![Screenshot of expanded project Gradle configuration tree](https://developers.home.google.com/static/apis/images/android-studio-project-gradle-configuration.png)
   | 6. The Signing Report appears in the lower panel. Look for the line that starts with**Store** . This tells you the location of the`debug.keystore`file.

   <br />

## Set up OAuth consent

1. In the Google Cloud console, go to the[project selector dashboard](https://console.cloud.google.com/projectselector/home/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. Click**Audience** and click the**+ ADD USERS**button.
   6. Enter your test user email address and click the**SAVE**button.
   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](https://support.google.com/cloud/answer/10311615#user-type&zippy=%2Ctesting%2Cexternal%2Cinternal)on the Google Cloud Console Help site for full details. Be sure to add at least one test user before continuing.

## Set up OAuth credentials

1. Register the Sample App for OAuth 2.0 and create OAuth credentials by following the instructions provided in[Setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849).
   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](https://support.google.com/cloud/answer/6158849#zippy=%2Cnative-applications%2Candroid:%7E:text=input%20device%20flow.-,Android,-Note%3A%20Currently%2C%20obtaining)on the Google Cloud Console Help site. You should generate the SHA-1 key from the default Android Studio key throughout the development process.

## Run the app

1. 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**.