Compila la app de ejemplo para iOS

Esta aplicación de iOS de ejemplo 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 la versión 15.3 o posterior de Xcode instalada.

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) que ejecute iOS 16.4 o una versión posterior configurado con la cuenta de prueba
  4. Una red Wi-Fi
  5. Un concentrador de Google que admita las APIs de Home
  6. Una Thread Border Router (TBR) si tu dispositivo requiere Thread y tu unidad central 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 App Attest. Como resultado, no se puede implementar en dispositivos simuladores. Para ello, debes crear un perfil de aprovisionamiento con el derecho de App Attest.

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

Para obtener más detalles, consulta la página de Apple Crea un perfil de aprovisionamiento de desarrollo sobre los perfiles de aprovisionamiento.

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 el MatterExtension.
    1. Accede al portal para desarrolladores de Apple.
    2. Agrega un identificador de grupo de apps. Por ejemplo, podría tener el formato group.com.company.commissioning.
  2. Registra tu dispositivo de prueba en la cuenta de 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 App Attest y Grupos de apps.

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

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

  4. Crea un perfil para tu destino 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 te solicite, agrega la función App Group.
    3. Edita el ID de app recién creado y configura la función App Groups para agregar el identificador de grupo de apps registrado que creaste en los pasos anteriores.
    4. Crea 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 ante el backend de autenticación de Google. Para 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 de 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 quieres usar para crear credenciales de OAuth.
  2. Para ir a la página 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 se configuró tu pantalla de consentimiento de OAuth y su estado de publicación es Prueba, asegúrate de que las cuentas de prueba que usarás se agreguen al grupo 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 mostrará el panel Pantalla de consentimiento de OAuth.
    2. Ingresa información en la página 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 necesitas agregar ningún permiso, así que haz clic en Guardar y continuar. Se muestra 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 la Cuenta de Google y, luego, haz clic en Agregar.
    5. Haga clic en Guardar y continuar. Aparecerá el panel Resumen.
    6. Revisa la información de la pantalla de consentimiento de OAuth y, luego, haz clic en Volver al panel.

  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 CREAR y toma nota del ID de cliente creado o DESCARGAR PLIST. Esto se usará más adelante para habilitar la funcionalidad del flujo de permisos. Para obtener más información, consulta la sección Crea 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. Busca HOME API y selecciónalo.
  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.

Agrega el SDK al proyecto

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, propagar la información del identificador de tu cuenta de desarrollador y propagar 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 de Xcode para la app de ejemplo:

  1. Desempaqueta el SDK descargado en el directorio ThirdParty/GoogleHomeSDK en relación con el directorio raíz del proyecto.
  2. 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.

  3. En el archivo Info.plist, completa el GIDClientID con tu ID de cliente de OAuth (consulta la sección Configura el consentimiento de OAuth), el Cloud Project Number correspondiente a tu proyecto de Cloud y el 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.

  4. 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 destino GoogleHomeAPISampleIOS 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 esta función no aparece en la búsqueda, es posible que el proyecto ya la haya agregado.

  5. Agrega la función App Groups.

    Agrega grupos de apps

    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 App Groups para la app que agregaste en el portal para desarrolladores de Apple.
    5. Repite estos pasos para el destino MatterAddDeviceExtension y agrégalo a los grupos de apps.

  6. Actualiza el identificador de paquete

    1. Para ejecutar e 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 destino GoogleHomeAPISampleIOS en el lado izquierdo, en la sección TARGETS.
    4. Selecciona el campo identificador de paquete en la sección Signing 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 con el objetivo de ingresar el identificador de paquete de la extensión y, luego, importar su perfil de aprovisionamiento registrado.

  7. 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 del grupo de apps para funciones como la puesta en marcha del dispositivo. Actualiza la app para usar el ID del grupo de apps registrado en el portal para desarrolladores de Apple. Para ello, busca la cadena HOME_API_TODO_ADD_APP_GROUP y reemplaza cada instancia por ella.

    Estas opciones de configuración se establecen en los siguientes archivos:

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

  8. Configura el permiso de OAuth en GoogleHomeAPISampleIOS.swift. De forma predeterminada, el código fuente de la app de ejemplo usa el permiso https://www.googleapis.com/auth/home.platform.v2. Muchas funciones de la app de ejemplo están restringidas por el permiso home.platform.v2 y requieren la aprobación del socio para acceder. Para ejecutar la app de ejemplo con el permiso estándar de https://www.googleapis.com/auth/home.platform.selected.devices, abre GoogleHomeAPISampleIOS.swift y cambia homePlatformOAuthScope en Home.configure a HomePlatformOAuthScope.v1:

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