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 the Android Studio is installed and signed into with this development account.
- A Wi-Fi network.
- To access and control Matter devices, 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. 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.

   | **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 sure Android Studio can 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 in Android 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 in
   Android Studio. When you run or debug an app in
   Android Studio, Android Studio automatically
   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 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](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**.