Compila la app de ejemplo para iOS

Esta aplicación de ejemplo para iOS usa las APIs de Google Home. Usa esta guía para compilar y ejecutar la app por primera vez.

Requisitos previos

Asegúrate de cumplir con los requisitos mínimos para usar las APIs de Home para iOS.

Para compilar e instalar la app de ejemplo, necesitarás una computadora con Xcode versión 15.3 o posterior instalado.

Descarga Xcode

Para probar la app, necesitarás lo siguiente:

  1. Una Cuenta de Google
  2. Un ID de Apple inscrito en el Programa para desarrolladores de Apple para generar archivos de configuración de dispositivos físicos. Si aún no se creó, la inscripción genera un costo adicional y puede tardar hasta 48 horas en completarse.
  3. Un dispositivo iOS (no un simulador) con iOS 16.4 o versiones posteriores configurado con la cuenta de prueba.
  4. Una red Wi-Fi
  5. Un dispositivo Google Hub que admita las APIs de Home.
  6. Un router Thread de borde si tu dispositivo requiere Thread y tu concentrador no tiene esa capacidad.
  7. Al menos un tipo de dispositivo compatible

Para el desarrollo, necesitarás una Mac que cumpla con los siguientes requisitos:

  • macOS Sonoma o versiones posteriores
  • Xcode 15.3 o una versión posterior

Crea archivos de configuración de implementación de Apple

Primero, una app requiere que se habilite la función de App Attest. Por lo tanto, no se puede implementar en dispositivos simuladores. Esto requiere que crees un perfil de aprovisionamiento con el derecho App Attest.

En segundo lugar, requiere que los grupos de apps estén habilitados para la comunicación entre la app y MatterExtension. Para ello, debes registrar un identificador de grupo de apps.

Para obtener más detalles, consulta el artículo de Apple sobre cómo crear un perfil de aprovisionamiento de desarrollo.

A continuación, se describen los pasos mínimos necesarios para implementar una app:

  1. Crea un identificador de grupo de apps para que tu app se comunique con MatterExtension.
    1. Accede al Apple Developer Portal.
    2. Agrega un identificador de grupo de apps. Por ejemplo, podría tener el formato group.com.company.commissioning.
  2. Registre su dispositivo de prueba en la cuenta del desarrollador.

  3. Crea un perfil para el destino de tu app.

    1. Decide un identificador de paquete de aplicación para tu app. El identificador debe ser único y descriptivo. Por ejemplo, podría tener el formato com.company.HomeApiSample. Este identificador se usará en el resto de esta sección.
    2. Registra tu ID de app. Cuando se te solicite, agrega las funciones de App Attest y App Groups.

    3. Edita el ID de app recién creado y configura la capacidad de Grupos de apps para agregar el identificador del grupo de apps registrado.

    4. Crea un perfil de aprovisionamiento de desarrollo para el desarrollo de tu aplicación. Asócialo al ID de app que acabas de crear y a los dispositivos de prueba seleccionados. Asegúrate de tener un certificado de desarrollador para firmar la app.

  4. Crea un perfil para tu objetivo de MatterExtension.

    1. Decide un identificador de paquete de aplicación para tu MatterExtension. El identificador debe heredarse del identificador de la app. Por ejemplo, podría tener el formato com.company.HomeApiSample.MatterExtension.
    2. Registra tu ID de app. Cuando se le solicite, agregue la capacidad Grupo de aplicaciones.
    3. Edite el ID de la aplicación recién creado y configure la capacidad Grupos de aplicaciones para agregar el identificador del grupo de aplicaciones registrado creado en los pasos anteriores.
    4. Crear un perfil de aprovisionamiento de desarrollo para MatterExtension.

Genera el ID de cliente de OAuth y habilita las APIs de Home

Tu app necesita un ID de cliente de OAuth para identificarse en el backend de autenticación de Google. En el caso de iOS y las apps, el tipo de aplicación del ID de cliente de OAuth debe configurarse como iOS. La app también realizará llamadas a la API de Home. Para habilitar esta funcionalidad, la API debe estar habilitada en el proyecto Google Cloud.

Genera el ID de cliente de OAuth

  1. En la consola de Google Cloud, ve al panel del selector de proyectos y selecciona el proyecto que deseas usar para crear credenciales de OAuth.
  2. Para ir a la página de APIs y servicios, haz clic en el botón de menú en la parte superior izquierda > Ver todos los productos > APIs y servicios.
  3. En el menú de navegación, haz clic en Credenciales.

  4. Si aún no configuraste la pantalla de consentimiento para este proyecto de Google Cloud, aparecerá el botón Configurar pantalla de consentimiento. En ese caso, configura la pantalla de consentimiento con el siguiente procedimiento. Si ya configuraste la pantalla de consentimiento de OAuth y su estado de publicación es Pruebas, asegúrate de que las cuentas de prueba que usarás se agreguen al grupo de Usuarios de prueba. De lo contrario, continúa con el siguiente paso.

    1. Según tu caso de uso, selecciona Interno o Externo y, luego, haz clic en Crear. Se muestra el panel Pantalla de consentimiento de OAuth.
    2. Ingresa la información en la página de información de la app según las instrucciones en pantalla y, luego, haz clic en Guardar y continuar. Aparecerá el panel Scopes.
    3. No es necesario que agregues ningún alcance, así que haz clic en Guardar y continuar. Aparecerá el panel Usuarios de prueba.
    4. Si optaste por crear una pantalla de consentimiento interna, debes agregar usuarios para probar el acceso a tu app. Haz clic en Agregar usuarios. Aparecerá el panel Agregar usuarios. Los usuarios de prueba tienen el privilegio de otorgar permisos en tu app. En el campo vacío, agrega una o más direcciones de correo electrónico de Cuentas de Google y, luego, haz clic en Agregar.
    5. Haga clic en Guardar y continuar. Aparecerá el panel Resumen.
    6. Revise la información de la pantalla de consentimiento de OAuth y luego haga clic en Volver al panel de control.

  5. En el panel del menú de la izquierda, haz clic en Credenciales para crear tu ID de cliente de OAuth.

    Configura la pantalla de OAuth

    1. Haz clic en el botón CREAR CREDENCIALES y selecciona ID de cliente de OAuth.
      1. En Tipo de aplicación, selecciona iOS.
    2. Ingresa el ID del paquete con el identificador de tu app y el ID del equipo de desarrolladores de Apple. Los demás campos son opcionales y se pueden dejar en blanco.
    3. Haz clic en CREATE y anota el ID de cliente o DESCARGAR PLIST creados. Esto se usará más adelante para habilitar la funcionalidad del flujo de permisos. Para obtener más información, consulte la sección Crear credenciales de autorización.

Habilita las APIs de Home

Habilita el acceso a las APIs de Home.

  1. En la pestaña APIs y servicios, haz clic en APIs y servicios habilitados.
  2. Haz clic en HABILITAR APIS Y SERVICIOS en la parte superior de la página.
  3. Busque HOME API y selecciónelo.
  4. En la página de detalles de la API de Home, haz clic en HABILITAR.

Descarga el código fuente

El código fuente de la app de ejemplo está disponible en GitHub.

Navega hasta donde quieras guardar el proyecto y, luego, clónalo:

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

Para cargar el proyecto en Xcode, haz clic en File > Open y selecciona GoogleHomeAPISampleIOS.xcodeproj en la raíz del repositorio clonado.

Configura el SDK

El proyecto de la app de ejemplo requiere información adicional para compilarse. Esto incluye agregar de forma local los archivos del framework del SDK, completar la información del identificador de tu cuenta de desarrollador y completar tu ID de cliente de OAuth.

Compila la app

Para descargar el SDK de las APIs de Home para iOS, primero debes acceder a Google Home Developers.

Accede ahora

Configura tu proyecto Xcode para la app de ejemplo:

  1. En el panel de navegación de Xcode, selecciona el archivo GoogleHomeAPISampleIOS para editar la configuración del proyecto.

    Configura la app de ejemplo del SDK

  2. Haz clic en la pestaña General en la parte superior y selecciona el objetivo GoogleHomeAPISampleIOS a la izquierda.

  3. Desplázate hacia abajo hasta que veas la sección Frameworks, Libraries, and Embedded Content. Deberías ver los dos frameworks de la API de Home.

  4. En la columna Embed, seleccione Embed & Sign para GoogleHomeSDK.xcframework. El otro framework, GoogleHomeTypes.xcframework, debe dejarse como No incorporar.

  5. Al final de la lista, haga clic en el icono +.

  6. Cuando se te solicite, busca SafariServices.framework y haz clic en Agregar. Asegúrese de que la columna Insertar esté configurada en No insertar para esta entrada.

    Incorporar y firmar

  7. Haz clic en MatterAddDeviceExtension en Objetivo para editarlo.

  8. Desplázate hacia abajo hasta que veas la sección Frameworks and Libraries. Deberías ver GoogleHomeSDK.xcframework en la lista.

  9. En la columna Insertar, seleccione No insertar.

  10. Configura los IDs de cliente de OAuth y de desarrollador:

    1. En el panel de navegación, busca la carpeta GoogleHomeAPISampleIOS y abre el archivo Info.plist para editarlo.

  11. En el archivo Info.plist, completa GIDClientID con tu ID de cliente de OAuth (consulta la sección Configura el consentimiento de OAuth), Cloud Project Number con el número de tu proyecto de Cloud y GIDTeamID con el ID del equipo de desarrolladores de Apple de la cuenta de desarrollador que se usó durante el proceso de registro de OAuth.

  12. Agrega la función App Attest:

    1. En el panel de navegación de Xcode, selecciona el archivo de proyecto GoogleHomeAPISampleIOS para editar la configuración del proyecto.
    2. Haz clic en la pestaña Signing and Capabilities en la parte superior y selecciona el GoogleHomeAPISampleIOS de destino en el lado izquierdo, en la sección TARGETS.
    3. Justo debajo de la pestaña Signing and Capabilities, haz clic en + Capability y busca App Attest.
    4. Haz clic en App Attest para agregarla. Si falta esta capacidad en la búsqueda, es posible que el proyecto ya la haya agregado.

  13. Agrega la función App Groups.

    Agrega grupos de aplicaciones

    1. Ve al proyecto GoogleHomeAPISampleIOS > destino GoogleHomeAPISampleIOS.
    2. Haz clic en Signing & Capabilities > + Capability.
    3. Selecciona la función App Groups.
    4. Haz clic en el ícono + en App Groups y agrega el identificador de los grupos de apps de tu app que agregaste en Apple Developer Portal.
    5. Repita estos pasos para el objetivo MatterAddDeviceExtension para agregarlo a los Grupos de aplicaciones.

  14. Actualiza el identificador del paquete

    1. Para ejecutar y, luego, implementar correctamente la app de ejemplo en el hardware con tus certificados de desarrollador y perfiles de aprovisionamiento, deberás proporcionar un identificador de paquete único. Debe ser el mismo identificador asociado con tus credenciales de cliente de OAuth (consulta más arriba).
    2. En el panel de navegación de Xcode, selecciona el archivo de proyecto GoogleHomeAPISampleIOS para editar la configuración del proyecto.
    3. Haz clic en la pestaña Signing and Capabilities en la parte superior y selecciona el GoogleHomeAPISampleIOS de destino en el lado izquierdo, en la sección TARGETS.
    4. Selecciona el campo Identificador del paquete en la sección Firma y, luego, ingresa el identificador único de la aplicación.
    5. Selecciona o instala el perfil de aprovisionamiento relacionado con ese paquete con los derechos requeridos.
    6. Repite estos pasos para el destino MatterAddDeviceExtension para ingresar el identificador del paquete de la extensión y, luego, importar su perfil de aprovisionamiento registrado.

  15. Actualiza el identificador del grupo de apps registrado en el código.

    1. La aplicación debe configurar la instancia del SDK para usar el identificador de grupo de la app en funciones como la puesta en servicio del dispositivo. Actualiza la app para que use el ID de grupo de la app registrado en Apple Developer Portal. Para ello, busca la cadena HOME_API_TODO_ADD_APP_GROUP y reemplaza cada instancia por el ID.

    Estas configuraciones se realizan en los siguientes archivos:

    • GoogleHomeAPISampleIOS.swift cuando se inicializa el SDK
    • RequestHandler.swift
    • CommissioningManager.swift