Создайте пример приложения iOS

Этот пример приложения для iOS использует API Google Home. Используйте это руководство для первой сборки и запуска приложения.

Предпосылки

Убедитесь, что у вас есть минимальные требования для использования Home API для iOS.

Для сборки и установки примера приложения вам понадобится компьютер с установленной версией Xcode 15.3+.

Загрузить Xcode

Для тестирования приложения вам понадобится:

  1. Аккаунт Google .
  2. Apple ID, зарегистрированный в программе Apple Developer Program для создания файлов конфигурации физических устройств. Если он ещё не создан, регистрация потребует дополнительной оплаты и может занять до 48 часов.
  3. Устройство iOS (не симулятор) под управлением iOS 16.4+, настроенное с тестовой учетной записью.
  4. Сеть Wi-Fi.
  5. Центр Google, поддерживающий Home API .
  6. Пограничный маршрутизатор Thread, если вашему устройству требуется Thread, а ваш концентратор не имеет такой возможности.
  7. По крайней мере один поддерживаемый тип устройства .

Для разработки вам понадобится Mac, отвечающий следующим требованиям:

  • macOS Sonoma или более поздняя версия
  • Xcode 15.3 или более поздняя версия

Создание файлов конфигурации развертывания Apple

Во-первых, для приложения требуется включить функцию App Attest . Поэтому его невозможно развернуть на устройствах-симуляторах. Для этого необходимо создать профиль подготовки с правом App Attest .

Во-вторых, для взаимодействия между приложением и MatterExtension необходимо включить группы приложений. Для этого необходимо зарегистрировать идентификатор группы приложений.

Более подробную информацию см. в статье Apple «Создание профиля обеспечения разработки» на странице профилей обеспечения.

Ниже описаны минимальные шаги, необходимые для развертывания приложения:

  1. Создайте идентификатор группы приложений, чтобы ваше приложение могло взаимодействовать с MatterExtension .
    1. Войдите на портал разработчиков Apple .
    2. Добавьте идентификатор группы приложений . Например, он может иметь формат group.com.company.commissioning .
  2. Зарегистрируйте свое тестовое устройство в учетной записи разработчика.

  3. Создайте профиль для вашего целевого приложения.

    1. Выберите идентификатор пакета приложения для вашего приложения. Идентификатор должен быть уникальным и описательным. Например, он может быть отформатирован какcom.company.HomeApiSample . Этот идентификатор будет использоваться далее в этом разделе.
    2. Зарегистрируйте свой идентификатор приложения . При появлении запроса добавьте возможности App Attest и App Groups .

    3. Отредактируйте недавно созданный идентификатор приложения и настройте возможность групп приложений , чтобы добавить зарегистрированный идентификатор группы приложений.

    4. Создайте профиль обеспечения разработки для вашего приложения. Свяжите его с вашим новым идентификатором приложения и выбранными тестовыми устройствами. Убедитесь, что у вас есть сертификат разработчика для подписи приложения.

  4. Создайте профиль для вашего целевого объекта MatterExtension .

    1. Выберите идентификатор пакета приложения для вашего MatterExtension . Идентификатор должен быть унаследован от идентификатора приложения. Например, он может быть отформатирован как com.company.HomeApiSample.MatterExtension .
    2. Зарегистрируйте свой идентификатор приложения . При появлении запроса добавьте возможность группы приложений .
    3. Отредактируйте только что созданный идентификатор приложения и настройте возможность групп приложений , чтобы добавить зарегистрированный идентификатор группы приложений, созданный на предыдущих шагах.
    4. Создайте профиль обеспечения разработки для MatterExtension .

Сгенерируйте идентификатор клиента OAuth и включите Home API

Вашему приложению необходим идентификатор клиента OAuth для идентификации в системе аутентификации Google. Для iOS и приложений тип приложения идентификатора клиента OAuth должен быть настроен как iOS. Приложение также будет выполнять вызовы к Home API. Для включения этой функции API должен быть включен в проекте Google Cloud .

Сгенерируйте идентификатор клиента OAuth

  1. В консоли Google Cloud перейдите на панель выбора проектов и выберите проект, который вы хотите использовать для создания учетных данных OAuth.
  2. Перейдите на страницу API и сервисы, нажав кнопку меню в левом верхнем углу > Просмотреть все продукты > API и сервисы .
  3. В навигационном меню нажмите Учетные данные .

  4. Если вы ещё не настроили экран согласия для этого проекта Google Cloud, появится кнопка «Настроить экран согласия» . В этом случае настройте экран согласия, следуя следующей процедуре. Если экран согласия OAuth уже настроен и его статус публикации — «Тестирование» , убедитесь, что тестовые учётные записи, которые вы будете использовать, добавлены в группу «Тестовые пользователи» . В противном случае перейдите к следующему шагу.

    1. В зависимости от вашего варианта использования выберите «Внутренний» или «Внешний» , а затем нажмите «Создать» . Откроется экран согласия OAuth .
    2. Введите информацию на странице «Информация о приложении» в соответствии с инструкциями на экране, затем нажмите «Сохранить и продолжить» . Откроется панель «Области действия».
    3. Добавлять области действия не нужно, поэтому нажмите «Сохранить и продолжить» . Откроется панель «Тестовые пользователи» .
    4. Если вы решили создать внутренний экран согласия, необходимо добавить пользователей для тестового доступа к приложению. Нажмите «Добавить пользователей» . Откроется панель «Добавить пользователей» . Тестовые пользователи имеют право предоставлять разрешения в вашем приложении. В пустом поле добавьте один или несколько адресов электронной почты учётной записи Google и нажмите «Добавить» .
    5. Нажмите «Сохранить и продолжить» . Откроется панель «Сводка» .
    6. Проверьте информацию на экране согласия OAuth, а затем нажмите « Вернуться на панель управления» .

  5. На левой панели меню нажмите «Учетные данные» , чтобы создать идентификатор клиента OAuth.

    Настройка экрана OAuth

    1. Нажмите кнопку СОЗДАТЬ УЧЕТНЫЕ ДАННЫЕ и выберите Идентификатор клиента OAuth .
      1. В качестве типа приложения выберите iOS .
    2. Введите идентификатор пакета , включающий идентификатор вашего приложения и идентификатор команды разработчиков Apple . Остальные поля необязательны и могут быть оставлены пустыми.
    3. Нажмите кнопку «СОЗДАТЬ» и запишите созданный Client ID или DOWNLOAD PLIST . Он будет использоваться позже для включения функции потоков разрешений. Подробнее см. в разделе «Создание учётных данных авторизации» .

Включить Home API

Включить доступ к API Home.

  1. На вкладке API и службы нажмите Включенные API и службы .
  2. Нажмите ВКЛЮЧИТЬ API И СЕРВИСЫ в верхней части страницы.
  3. Найдите HOME API и выберите его.
  4. На странице сведений о Home API нажмите ВКЛЮЧИТЬ .

Загрузить исходный код

Исходный код примера приложения доступен на GitHub.

Перейдите туда, где вы хотите сохранить проект, затем клонируйте его:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

Чтобы загрузить проект в Xcode, нажмите Файл > Открыть и выберите GoogleHomeAPISampleIOS.xcodeproj в корне клонированного репозитория.

Настройте SDK

Для сборки проекта Sample App требуется некоторая дополнительная информация. В частности, необходимо добавить файлы SDK Framework локально, указать идентификатор вашей учётной записи разработчика и идентификатор клиента OAuth.

Создайте приложение

Чтобы загрузить Home APIs iOS SDK, сначала необходимо войти в систему Google Home Developers.

Войдите сейчас!

Настройте свой проект Xcode для примера приложения:

  1. На панели навигации Xcode выберите файл GoogleHomeAPISampleIOS , чтобы изменить конфигурацию проекта.

    Настроить пример приложения SDK

  2. Нажмите вкладку «Общие» вверху и выберите целевой GoogleHomeAPISampleIOS слева.

  3. Прокрутите страницу вниз, пока не увидите раздел «Фреймворки, библиотеки и встроенный контент» . В нём вы увидите два фреймворка Home API.

  4. В столбце «Встроить» выберите «Встроить и подписать» для GoogleHomeSDK.xcframework . Для другого фреймворка, GoogleHomeTypes.xcframework , следует оставить значение «Не встраивать» .

  5. Внизу списка нажмите значок + .

  6. При появлении запроса найдите SafariServices.framework и нажмите кнопку «Добавить» . Убедитесь, что в столбце «Встроить» для этой записи установлено значение «Не встраивать» .

    Встроить и подписать

  7. Щелкните MatterAddDeviceExtension в разделе Target , чтобы изменить его цель.

  8. Прокрутите страницу вниз, пока не увидите раздел «Фреймворки и библиотеки» . В нём должен быть GoogleHomeSDK.xcframework .

  9. В столбце «Встроить» выберите «Не встраивать» .

  10. Настройте идентификаторы разработчика и клиента OAuth:

    1. В панели навигации найдите папку GoogleHomeAPISampleIOS и откройте файл Info.plist для редактирования.

  11. В файле Info.plist заполните поле GIDClientID идентификатором вашего клиента OAuth (см. раздел «Настройка согласия OAuth» ), номером облачного проекта, соответствующим вашему облачному проекту, а поле GIDTeamID — идентификатором команды разработчиков Apple для учетной записи разработчика, использованной во время процесса регистрации OAuth.

  12. Добавить возможность подтверждения подлинности приложения:

    1. На панели навигации Xcode выберите файл проекта GoogleHomeAPISampleIOS , чтобы изменить конфигурацию проекта.
    2. Нажмите вкладку «Подписание и возможности» вверху и выберите целевой GoogleHomeAPISampleIOS слева в разделе «ЦЕЛИ».
    3. Под вкладкой «Подписание и возможности» нажмите + Возможности и найдите App Attest .
    4. Нажмите «App Attest» , чтобы добавить. Если эта возможность отсутствует в результатах поиска, возможно, она уже добавлена ​​в проект.

  13. Добавьте возможность групп приложений .

    Добавить группы приложений

    1. Перейдите в проект GoogleHomeAPISampleIOS > цель GoogleHomeAPISampleIOS .
    2. Нажмите Подписание и возможности > + Возможность .
    3. Выберите возможность « Группы приложений» .
    4. Нажмите значок + под группами приложений и добавьте идентификатор групп приложений для вашего приложения, который вы добавили на портале разработчиков Apple.
    5. Повторите эти шаги для цели MatterAddDeviceExtension , чтобы добавить ее в App Groups .

  14. Обновить идентификатор пакета

    1. Для успешного запуска и развертывания примера приложения на оборудовании с использованием ваших сертификатов разработчика и профилей подготовки вам потребуется предоставить уникальный идентификатор пакета. Он должен совпадать с идентификатором, связанным с вашими учётными данными клиента OAuth (см. выше).
    2. На панели навигации Xcode выберите файл проекта GoogleHomeAPISampleIOS , чтобы изменить конфигурацию проекта.
    3. Нажмите вкладку «Подписание и возможности» вверху и выберите целевой GoogleHomeAPISampleIOS слева в разделе «ЦЕЛИ».
    4. Выберите поле «Идентификатор пакета» в разделе «Подписание» и введите уникальный идентификатор приложения.
    5. Выберите или установите профиль обеспечения, связанный с этим пакетом, с требуемыми правами.
    6. Повторите эти шаги для цели MatterAddDeviceExtension , чтобы ввести идентификатор пакета для расширения и импортировать его зарегистрированный профиль подготовки.

  15. Обновите зарегистрированный идентификатор группы приложений в коде.

    1. Приложению необходимо настроить экземпляр SDK для использования идентификатора группы приложений (App Group ID) для таких функций, как ввод в эксплуатацию устройств. Обновите приложение, чтобы использовать идентификатор группы приложений, зарегистрированный на портале разработчиков Apple. Для этого найдите строку HOME_API_TODO_ADD_APP_GROUP и замените ею каждый экземпляр.

    Эти конфигурации сделаны в следующих файлах:

    • GoogleHomeAPISampleIOS.swift при инициализации SDK.
    • RequestHandler.swift
    • CommissioningManager.swift