Add the Home APIs to your iOS app

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.

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 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.
   2. Add an app group identifier. For example, it could be formatted as group.com.company.commissioning.
2. Register your test 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. 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 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 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. 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 for MatterExtension.

Supported hubs

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

Apart from these supported hubs, there is a Hubless Mode that offers limited Home APIs capabilities.

Set up the iOS SDK

In order to develop applications with the Home APIs for iOS, you need to set it up in Xcode. The SDK is packaged in both Cocoapods and Swift Package Manager formats.

Your download and use of any Home APIs SDK is subject to the Terms of Service for Google Home Developers.

The SDK may be integrated into your project using the Swift Package Manager (SwiftPM), Cocoapods, 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 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.

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:

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

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:

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