To add the Home APIs to an iOS app, you'll need to meet a few prerequisites.

## Prerequisites

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.MyCompanyApp`. 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.MyCompanyApp.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`.

### Supported hubs

Only certain Google Nest hubs feature support for the Home APIs.

| Device | Thread border router support | Google Store |
|---|:---:|:---:|
| Google Home |   |   |
| Google Nest Audio |   | [](https://store.google.com/us/product/nest_audio) |
| Google Nest Hub |   |   |
| Google Nest Hub (2nd gen) | Yes | [](https://store.google.com/us/product/nest_hub_2nd_gen) |
| Google Nest Hub Max | Yes | [](https://store.google.com/us/product/google_nest_hub_max) |
| Google Nest Mini |   | [](https://store.google.com/us/product/google_nest_mini) |
| Google TV Streamer (4k) | Yes | [](https://store.google.com/product/google_tv_streamer) |
| Nest WiFi Pro | Yes | [](https://store.google.com/product/nest_wifi_pro) |
[*Table: Google Nest hubs with Home APIs
support*]

## Set up the iOS SDK

In order to develop applications with the Home APIs for iOS, you need to
download and host the libraries locally.

**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/sdk&prompt=select_account)

The SDK may be integrated into your project using the [Swift Package
Manager](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/)
(SwiftPM),
[Cocoapods](https://cocoapods.org/), or manually.

### Swift Package Manager setup

The Swift Package Manager is the preferred method for managing dependencies in
modern Swift projects, and is integrated into the Swift build system.

#### Verify the package (optional)

To verify the Swift SDK package, navigate to the root directory of the package
and run the following command:

    swift package describe

Then run the following Xcode test command:

    xcodebuild test -scheme GoogleHomeSDK -destination 'platform=iOS Simulator,name=iPhone 16,OS=18.0'

#### Add the SDK to your Xcode project

To add the SDK to your project:

1. Open your project in Xcode.
2. Unpack the SDK into the `ThirdParty/GoogleHomeSDK` directory relative to your project root.
3. Select **File \> Add Package Dependencies...** , then select **Add Local...**
4. Select the `GoogleHomeSDK` directory.
5. In the **Add to Target** column, select your app target for both `GoogleHomeSDK` and `GoogleHomeTypes`.

#### Handle static embedding of the SDK

If you get either of the two following error messages, it may be because Xcode
has incorrectly tried to embed the static `GoogleHomeTypes` framework
into the app bundle:

- *failed to install*
- *did not contain an Info.plist*

If this happens, add a "Run
Script" build phase that runs after the "Embed Frameworks"
phase and removes the static framework from the built app bundle:

1. In the top toolbar, select your target name and choose **Edit Scheme...**.
2. In the left sidebar, select the arrow next to **Build** to expand it. Then, select **Post-actions**.
3. Click the add icon to add a **New Run Script Action**.
4. For \***Provide build settings from**, select your app target.
5. Paste the script:

       echo "Removing wrongly embedded static framework..."
       rm -rf "${TARGET_BUILD_DIR}/${FRAMEWORKS_FOLDER_PATH}/GoogleHomeTypes.framework"

6. Close the window and select your app target's **Build Phases** tab. Then,
   click the add icon, choose
   **New Run Script Phase**, and paste the script.

7. This script must run after the "Embed Frameworks" phase, so be sure to
   clear the **based on dependency analysis** checkbox, and set the **User
   Script Sandboxing** build option to **No**.

If this doesn't solve the problem, try deleting everything in the `build`
directory by first selecting **Product \> Clean Build Folder** from the menu bar.

### CocoaPods setup

[Cocoapods](https://cocoapods.org/) is a dependency
management tool for Xcode projects, and has long been the de-facto solution for
building iOS apps. If you are new to Cocoapods, follow the directions on
[the Cocoapods Getting Started
page](https://guides.cocoapods.org/using/getting-started.html).

The SDK package supports integration with CocoaPods as a "Development Pod" by
adding the following to an existing Podfile and running pod install:

    pod 'GoogleHomeSDK', :path => 'ThirdParty/GoogleHomeSDK', :subspecs => ['SDK', 'Types']

#### Verify the Pod (optional)

To verify the Pod can be installed, run the the following command. This command
generates and builds a sample Xcode project, and also runs unit tests to verify
that the SDK can be linked into an app.

    pod lib lint

#### Add the SDK to your Xcode project

Add the following to your `Podfile`:

```ruby
pod 'GoogleHomeSDK', :path => 'ThirdParty/GoogleHomeSDK', :subspecs => ['SDK', 'Types']
```

Make sure to add `$(inherited)` to the **Other Linker Flags** setting and set
the **User Script Sandboxing** option to **No** within your app target's **Build
Settings**.

Then, in the directory that contains the `Podfile`, execute

    pod install

> [!IMPORTANT]
> **Important:** Make sure to always open the `.xcworkspace` file from now on in Xcode.

##### Workaround for "Multiple commands produce"

Occasionally, there's an issue with Xcode and CocoaPods script phases that
causes a build error. To resolve this, add the following line to your Podfile:

```ruby
install! 'cocoapods', :disable_input_output_paths => true
```

### Manual setup

If you don't want to use either package management tools, you can manually
integrate the SDK into your project:

1. Open your app project in Xcode.
2. Drag the `GoogleHomeSDK.xcframework` and `GoogleHomeTypes.xcframework` bundles into Xcode's Project Navigator.
3. Select your app target, go to the **General** tab, and in the **Frameworks,
   Libraries, and Embedded Content** section, make sure that both xcframeworks are present and that **Embed \& Sign** is selected for each.
4. Go to the **Build Phases** tab, expand **Link Binary With Libraries** section, and add the following system frameworks and libraries if they are not yet present:
   - `Combine`
   - `CryptoKit`
   - `Foundation`
   - `Matter`
   - `UIKit`
   - `libc++`
   - `libsqlite3`
   - `libz`