This sample iOS application uses the Google Home APIs. Use this guide to build
and run the app for the first time.

## Prerequisites

Ensure that you have the minimum requirements to use the Home APIs for iOS.

To build and install the Sample App, you'll need a computer with Xcode version
15.3+ installed on it.

[Download Xcode](https://apps.apple.com/us/app/xcode/id497799835)

> [!NOTE]
> **Note:** Earlier versions of Xcode may not work properly with the Home APIs SDK.

To test the app, you'll need:

1. A [Google Account](https://myaccount.google.com/).
2. An Apple ID enrolled in the [Apple Developer
   Program](https://developer.apple.com/programs/) to generate physical device configuration files. If not created already, enrollment incurs an additional cost and may take up to 48 hours to complete.
3. An iOS device (not a simulator) running iOS 16.4+ set up with the test account.
4. A Wi-Fi network.
5. A [Google hub that supports the Home
   APIs](https://developers.home.google.com/apis/ios/sdk#supported_hubs).
6. A Thread Border Router (TBR) if your device requires Thread and your hub doesn't have that capability.
7. At least one [supported device type](https://developers.home.google.com/apis/supported-devices).

For development, you'll need a Mac that meets the following requirements:

- macOS Sonoma or later
- Xcode 15.3 or later

## Create Apple deployment configuration files

First, an app requires that the **App Attest** capability be enabled. As a
result, it cannot be deployed to simulator devices. This requires you to create
a provisioning profile with the **App Attest** entitlement.

> [!NOTE]
> **Note:** Enabling **App Attest** on an app with a large user base could see users impacted by attestation traffic throttling. See [Onboard users gradually](https://developer.apple.com/documentation/devicecheck/preparing-to-use-the-app-attest-service/#Onboard-users-gradually) for more information.

Second, it requires the App Groups be enabled for communication between the app
and the `MatterExtension`. This requires you to register an app group
identifier.

For more details, see Apple's
[Create a development provisioning profile](https://developer.apple.com/help/account/provisioning-profiles/create-a-development-provisioning-profile/)
on provisioning profiles.

The following outlines the minimum steps required to deploy an app:

1. Create an app group identifier for your app to communicate with the `MatterExtension`.
   1. Sign in to the [Apple Developer Portal](https://developer.apple.com/account/resources).
   2. Add an [app group identifier](https://developer.apple.com/account/resources/identifiers/list/applicationGroup). For example, it could be formatted as `group.com.company.commissioning`.
2. [Register your test device](https://developer.apple.com/help/account/register-devices/register-a-single-device/) to the developer account.
3. Create a profile for your app target.

   1. Decide on an application bundle identifier for your app. The identifier should be unique and descriptive. For example, it could be formatted as `com.company.HomeApiSample`. This identifier will be used throughout the rest of this section.
   2. [Register your App ID](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/). When prompted, add the **App Attest** and **App Groups** capability.
   3. Edit the newly created App ID and configure the **App Groups** capability
      to add the registered app group identifier.

   4. [Create a development provisioning profile](https://developer.apple.com/help/account/provisioning-profiles/create-a-development-provisioning-profile/)
      for your app development. Associate it to your newly created App ID
      and selected test devices. Ensure you have a developer certificate to sign
      the app with.

      - If you haven't created one yet, see [Create Developer ID certificates](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates/) for instructions.
4. Create a profile for your `MatterExtension` target.

   1. Decide on an application bundle identifier for your `MatterExtension`. The identifier should be inherited from the app identifier. For example, it could be formatted as `com.company.HomeApiSample.MatterExtension`.
   2. [Register your App ID](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id/). When prompted, add the **App Group** capability.
   3. Edit the newly created App ID and configure the **App Groups** capability to add the registered app group identifier created in the previous steps.
   4. [Create a development provisioning profile](https://developer.apple.com/help/account/provisioning-profiles/create-a-development-provisioning-profile/) for `MatterExtension`.

## Generate the OAuth client ID and enable Home APIs

Your app needs an OAuth client ID to identify itself to Google's authentication
backend. For iOS and apps, the
[OAuth client ID application
type](https://support.google.com/cloud/answer/6158849)
must be configured as iOS. The app will also make
calls to the Home API. To enable this functionality, the API must be enabled in
the Google Cloud project.

### Generate the OAuth client ID

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 by clicking on the **menu button** on the top left hand side \> **View All Products** \> **APIs \& Services**.
3. In the navigation menu, click **Credentials**.
4. 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. If your OAuth
   consent screen has already been configured and its publishing status is
   **Testing** , ensure the test accounts you will use are added to the
   **Test users** group. Otherwise, move on to the next step.

   1. Depending on your use case, select **Internal** or **External** , and then click **Create** . The **OAuth consent screen** pane displays.
   2. Enter information on the **App information page** according to the on-screen instructions, and then click **Save and continue**. The Scopes pane displays.
   3. You don't need to add any scopes, so click **Save and continue** . The **Test users** pane displays.
   4. If you opted to create an internal consent screen, you must 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. In the empty field, add one or more Google Account email addresses, and then click **Add**.
   5. Click **Save and continue** . The **Summary** pane displays.
   6. Review your OAuth consent screen information, and then click **Back to
      dashboard**.
5. On the left menu panel, click **Credentials** to create your OAuth client
   ID.

   ![Set up OAuth screen](https://developers.home.google.com/static/apis/eap/ios/images/ios-sample-app-set-oauth.png)

   ![](https://developers.home.google.com/static/apis/eap/ios/images/ios-sample-app-set-oauth.png)
   1. Click the **CREATE CREDENTIALS** button, and select **OAuth client ID** .
      1. Under **application type** , select **iOS**.
   2. Enter the **Bundle ID** with your app identifier and [Apple
      Developer **Team ID**](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/). The other fields are optional and can be left blank.
   3. Click **CREATE** , and note the created **Client ID** or **DOWNLOAD PLIST** . This will be used later to enable permissions flow functionality. For more information, see the [Create authorization
      credentials](https://developers.google.com/identity/protocols/oauth2/native-app#creatingcred) section.

### Enable the Home APIs

Enable access to the Home APIs.

1. In the **APIs and Services** tab, click **Enabled APIs \& Services**.
2. Click **ENABLE APIS AND SERVICES** at the top of the page.
3. Search for the **`HOME API`** and select it.
4. In the **Home API** detail page, click **ENABLE**.

## Download the source code

The [source
code](https://github.com/google-home/google-home-api-sample-app-ios)
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-ios.git

To load the project on Xcode, click **File** \> **Open** , and select
**`GoogleHomeAPISampleIOS.xcodeproj`** in the root of the cloned repository.

## Add the SDK to the project

The Sample App project requires some additional information in order to build.
This includes locally adding the SDK Framework files, populating your developer
account identifier information, and populating your OAuth client ID.

### Build the app

**To download the Home APIs iOS 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/ios/sample-app/build&prompt=select_account)

Configure your Xcode project for the Sample App:

1. Unpack the downloaded SDK into the `ThirdParty/GoogleHomeSDK` directory relative to the project root directory.
2. Configure the Developer and OAuth client IDs:
   1. In the navigation pane, look for the **GoogleHomeAPISampleIOS** folder and open the **Info.plist** file for editing.
3. In the **Info.plist** file, populate the **GIDClientID** with your OAuth
   client ID (see the [Set up OAuth
   consent](https://developers.home.google.com/apis/swift/sample-app/build#set_up_oauth_consent) section),
   **Cloud Project Number** corresponding to your cloud project, and the
   **GIDTeamID** with the [Apple Developer Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/)
   of the developer account used during the OAuth registration process.

4. Add App Attest Capability:

   1. In the Xcode navigation pane, select the **`GoogleHomeAPISampleIOS`** project file to edit the project configuration.
   2. Click the **Signing and Capabilities** tab on the top and select the target **`GoogleHomeAPISampleIOS`** on the left hand side under the TARGETS section.
   3. Just under the Signing and Capabilities tab, click **+ Capability** and search for **App Attest**.
   4. Click **App Attest** to add. If this capability is missing in the search, the project may already have added it.
5. Add the **App Groups** capability.

   ![Add app groups](https://developers.home.google.com/static/apis/ios/images/ios-sample-app-app-groups.png)

   ![](https://developers.home.google.com/static/apis/ios/images/ios-sample-app-app-groups.png)
   1. Go to the **GoogleHomeAPISampleIOS** project \> **GoogleHomeAPISampleIOS** target.
   2. Click **Signing \& Capabilities** \> **+ Capability**.
   3. Select the **App Groups** capability.
   4. Click the **+** icon under the **App Groups** and add the App Groups identifier for your app that you added in the Apple Developer Portal.
   5. Repeat these steps for the **MatterAddDeviceExtension** target to add it to the **App Groups**.
6. Update the Bundle identifier

   1. To successfully run and deploy the Sample App on hardware using your developer certificates and provisioning profiles, you will need to provide a unique bundle identifier. This should be the same identifier associated with your OAuth client credentials (see above).
   2. In the Xcode navigation pane, select the **`GoogleHomeAPISampleIOS`** project file to edit the project configuration.
   3. Click the **Signing and Capabilities** tab on the top and select the target **`GoogleHomeAPISampleIOS`** on the left hand side under the TARGETS section.
   4. Select the Bundle Identifier field in the **Signing** section and input the unique identifier for the Application.
   5. Select or install the provisioning profile related to that bundle with the required entitlements.
   6. Repeat these steps for the `MatterAddDeviceExtension` target to input the Bundle identifier for the extension and import its registered provisioning profile.

   > [!IMPORTANT]
   > **Important:** Two provisioning profiles are needed. One for **`GoogleHomeAPISampleIOS`** and one for **`MatterAddDeviceExtension`**.

7. Update the registered app group identifier in the code.

   1. The application is required to configure the SDK instance to make use of the App Group identifier for features such as device commissioning. Update the app to make use of the App Group ID registered in the Apple Developer Portal by searching for the string `HOME_API_TODO_ADD_APP_GROUP` and replace each instance with it.

   These configurations are made in the following files:
   - `GoogleHomeAPISampleIOS.swift` when the SDK is initialized.
   - `RequestHandler.swift`
   - `CommissioningManager.swift`
8. Configure the OAuth scope in `GoogleHomeAPISampleIOS.swift`. By default, the
   Sample App source code uses the
   `https://www.googleapis.com/auth/home.platform.v2` scope. Many features in
   the Sample App are gated by the `home.platform.v2` scope and require partner
   approval to access. To run the Sample App with the standard
   `https://www.googleapis.com/auth/home.platform.selected.devices` scope, open
   `GoogleHomeAPISampleIOS.swift` and change `homePlatformOAuthScope` in
   `Home.configure` to `HomePlatformOAuthScope.v1`:

   ```swift
   Home.configure {
     $0.sharedAppGroup = "HOME_API_TODO_ADD_APP_GROUP"
     $0.homePlatformOAuthScope = HomePlatformOAuthScope.v1
     ...
   }
   ```