Conoce App Intents

Hola, soy James, gerente de ingeniería en el equipo Swift Intelligence Frameworks. Me encantaría hablarte sobre App Intents, una estructura para ampliar la detección, visibilidad y capacidades de tu app en todo el sistema y las plataformas de Apple. Primero, platicaremos del papel cada vez más valioso de App Intents dentro de ecosistema de Apple Developer.

Luego, veremos cómo usar la estructura para que las personas en todo el sistema accedan a las acciones y entidades de tu app. Al final, compartiré detalles importantes que debes considerar al escribir tus App Intents.

Antes de analizar cómo usar App Intents, deberíamos hablar del porqué. App Intents es más que la estructura que incorporas a tu app para crear funcionalidades. Es un ecosistema que permite que la funcionalidad de tu app se expanda a todo el sistema.

Tus usuarios obtendrán resultados personalizados en Spotlight, experiencias adaptables para el botón de acción, configurabilidad e interactividad en Widgets, controles sencillos en el Centro de control y acciones personalizadas para el Apple Pencil Pro.

Este año, Spotlight puede invocar las acciones de tu app desde cualquier lugar en la Mac.

La estructura App Intents permite ofrecer vastas experiencias a tus clientes, incluso cuando no estén en tu app. Todo inicia con lo que tu app puede hacer: abrir una nota, iniciar un entrenamiento o agregar un artículo a una lista de compras. Estos son los verbos de tu app y, como ya te imaginarás, los describes cuando creas App Intents o intents. Cuando creas una intent, le das al sistema información adicional para realizar la acción correctamente. Estas toman parámetros y arrojan valores. Y estas entradas y salidas pueden ser tipos nativos de Swift o definidos en tu app. Puedes crear dos valores distintos con App Intents. Para tipos con un conjunto de valores constante usa una App Enum, y para los dinámicos, una App Entity. Las App Enums y App Entities son los sustantivos de tu app. Los atajos de apps permiten mejorar las intenciones clave, las hacen más accesibles y reconocibles. Los atajos de apps aparecen al buscar en Spotlight, usar Siri, configurar el botón de acción y más. Son como las oraciones de tu app, creadas a partir de una intención y los parámetros que esta necesita para ejecutarse. Creo que la mejor forma de aprender es con la práctica. Veamos qué necesito para crear mi primera intent. Amo viajar en familia y estuve trabajando en una app para visitar puntos de referencia en todo el mundo. Esta tiene algunas secciones. Puedo desplazarme por una lista de puntos de referencia, ubicarlos en un mapa o ver mis colecciones. Muchos prefieren la tabla de puntos de referencia. Crearé una App Intent que permita navegar directa y fácilmente a esta sección. ¿Cómo hago eso? Primero, definiré una estructura que adopte el protocolo AppIntent. Los requisitos mínimos para una App Intent son un título y método de ejecución.

El título es una cadena única y localizada que aparecerá como el nombre de la intent. El método de ejecución contiene la lógica. Abriré la vista de puntos de referencia con un navegador compartido. La navegación debe hacerse en el hilo principal, por lo que marcaré @MainActor.

El método de ejecución arroja un IntentResult. Los IntentResults pueden contener desde un diálogo que Siri puede decir hasta un fragmento de vista. Por defecto, ejecutar una intención no pondrá a tu app en primer plano, pero con un diálogo y un fragmento podrás mostrar el resultado de tu acción.

Dado que esta intent pretende navegar por las pantallas, la configuraré para que abra cuando se ejecute. Estableceré la nueva propiedad supportedModes en primer plano para abrir mi app antes de que se ejecute la intención y ya creé mi primera intent. Las intenciones de apps instaladas están en Atajos. Puedo crear un nuevo atajo y agregar mi intención de navegación. Al ejecutarla, mi app se pone en primer plano y abre la vista Puntos de referencia. En mi app también se pueden ver colecciones y ubicar puntos de referencia en un mapa. Sería genial si la intención también pudiera navegar a esas partes de la app. Mi app usa una enum Swift simple para modelar secciones. Para que el tipo sea compatible con la estructura, adoptaré el protocolo AppEnum. AppEnum tiene pocos requisitos. Debe ser instanciable desde una cadena, así que agregaré un valor crudo. Un TypeDisplayRepresentation describe el tipo como un todo y una caseDisplayRepresentation describe cada caso de la enum.

Estas representaciones deben ser constantes, ya que estos datos se usan en tiempo de compilación.

En mi intent, agregaré una variable para contener la navegación. Agregaré @Parameter para convertirlo en un parámetro de intent. Estos actúan como entradas para las intents. Pueden ser obligatorios u opcionales. Lo hice obligatorio para que se garantice la existencia de un valor antes de la ejecución.

Actualizaré el método de ejecución para usar la opción de Navegación y cambiaré el título para reflejar la nueva acción.

Al regresar a mi atajo, ahora la opción de navegación es un parámetro editable. Al ejecutar la intent, Atajos solicitará la sección. Elegiré Mapa y se abrirá directamente esa vista. Los tipos de App Intents están diseñados para ser personalizables. Esto permite colocar los componentes básicos en su lugar y mejorar la experiencia. Agregaré información adicional a la intención para mejorar su uso.

Los atajos mostrarán cada parámetro como una fila. Al tocar la fila aparecerá una lista de valores para ese tipo. Pero hay algunas cosas que puedo hacer para mejorar la experiencia.

Una App Enum requiere un título por cada caso de enum, pero se puede configurar con más información, como un ícono.

Para agregar uno, usaré el inicializador DisplayRepresentation. Luego, agregaré un símbolo a cada caso. Cuando lo haga, Atajos mostrará la imagen en el selector. Puedes configurar las intenciones con una representación fluida llamada Resumen de parámetros. Esta describe la acción y sus parámetros de una manera legible para las personas.

Proporcionaré el resumen con mi parámetro interpolado en la cadena. Los atajos mostrarán el resumen con el parámetro seleccionable en línea para una descripción más útil de la acción.

En realidad, esto aún no parece una oración. Agregaré un título personalizado a mi parámetro.

También agregaré un cuadro de diálogo personalizado cuando se solicite un valor. Como novedad este año, cuando implementes un Resumen de parámetros, con todos los parámetros requeridos, las personas podrán ejecutar tu acción desde Spotlight en la Mac. Para conocer más sobre las nuevas incorporaciones a Spotlight, ve esta sesión.

Al modelar las acciones de tu app como intents, tus clientes crearán atajos y automatizaciones avanzadas. Sin embargo, algunas intenciones son tan centrales para tu app que deben estar disponibles desde la instalación. Puedes proporcionarlas al adoptar Atajos de apps.

Un atajo de app es un tipo que expone automáticamente una App Intent en el sistema. Además, ocupan un lugar destacado al buscar en Spotlight. Con Siri, una frase desencadenante puede activar un atajo de app. Pueden configurarse para activarse con el botón de acción o con el Apple Pencil. Los atajos de app se muestran en la app Atajos sin configuraciones y lo mejor es que se desarrollan con un par de líneas de código. Veamos cómo.

Las apps ofrecen atajos de apps a través de un proveedor. Se debe definir un proveedor único para tu app con todos los atajos. Un atajo de app toma una instancia de una intent, así como frases, un título y una imagen. Las frases de un atajo se pueden decir o escribir a Siri para activarlo. Cada frase debe incluir el marcador applicationName. Pueden incluir hasta un parámetro de intent. Si se proporciona, se creará un atajo para cada valor de ese tipo.

Solo se necesita esta estructura simple para crear un atajo de app. Se mostrarán los atajos de tu app en una nueva sección. Las frases influyen en los atajos de apps que se crean. Al proporcionar una frase sin un parámetro, se creará un atajo con el título y el nombre de la imagen. Como proporcioné una frase con una App Enum, se creará un atajo para cada caso.

Ya puedo ejecutar mi intent con Siri o Spotlight. Los atajos son excelentes para que tus intents sean reconocibles. Para saber más sobre cómo crear atajos de apps, ve esta sesión de la WWDC23.

Los puntos de referencia son centrales en mi app. Sería genial que mis intents permitieran actuar sobre ellos. En Landmarks no puedo usar una App Enum, pues son dinámicos, no constantes. Crearé una App Entity para modelar Landmarks.

Mi app ya tiene un tipo de punto de referencia. Si bien podría adaptar ese tipo a una App Entity, voy a crear una nueva estructura LandmarkEntity. Este tipo será como un puente entre las App Intents y mi modelo de datos subyacente.

Agregaré una ID para que la entidad sea identificable. Es importante que esta ID sea persistente y que puedas buscar instancias de tu entidad con esta ID. Lo explicaremos más tarde. Al igual que los parámetros de una intent, el atributo @Property indica las propiedades de la entidad. Estos se expondrán a tus clientes en Atajos y se podrán usar en acciones de Buscar y filtrar. Este año, puedo agregar Getters a las propiedades de mi entidad, usando el nuevo atributo @ComputedProperty para establecer estos valores. En lugar de copiar valores entre estos tipos, puedo recurrir a mi modelo de datos. Al igual que las App Enums, las entidades requieren una representación del tipo y las instancias.

Las entidades necesitan una pieza de información adicional, una consulta.

A diferencia de una App Enum que tiene un conjunto conocido de valores, las entidades son dinámicas. Mi app puede tener varios puntos de referencia. Las consultas permiten a mi sistema razonar mis entidades. Lo hace respondiendo una serie de preguntas diferentes. La primera pregunta es: “¿Qué entidades existen?”. La consulta permite responder esa pregunta y devolver una colección de entidades coincidentes.

Las consultas admiten variaciones de la pregunta. Por ejemplo, una consulta de cadena pregunta: “¿Existen entidades que coincidan con esta cadena?”. Una de propiedad podría preguntar: “¿Cuáles son los puntos de referencia del estado?”. Las consultas deben responder a una pregunta: “¿Cuál es la entidad para esta ID?”, así el sistema puede referenciar una entidad y resolverla cuando sea necesario. Puedo proporcionar la consulta creando un tipo que siga el protocolo Entity Query. Con el método entities(for:) se puede responder “¿Qué entidad tiene esta ID?”. Toma un conjunto de identificadores y arroja uno de instancias de entidad. Después analizaremos la pregunta “¿Qué entidades existen?”. Las consultas necesitan acceso a una base de datos local u otra dependencia para obtener instancias. Con el atributo @Dependency puedo agregar dependencias a mi consulta. Tengo que registrar mi dependencia con el gestor de dependencias compartido. Debes registrar las dependencias lo antes posible en el ciclo de vida de tu app. Ya con una entidad de lugares famosos, puedo usarla desde mis intenciones. Cuando viajo, me gustaría saber cuál es el punto de referencia más cercano. Crearé una App Intent para verlo. Empezaré con la intent de punto de referencia más cercano. Debo obtener el punto más cercano desde mi modelo de datos. Las dependencias también son compatibles con las intents. Agregaré una. Para mi método de ejecución, agregaré ReturnsValue de LandmarkEntity. Los parámetros de intent también pueden devolverse desde una intent. El valor que se devuelve puede ser una entrada a otra intent, como en un atajo de varios pasos. También devolveré un cuadro y un fragmento. Esto permite que mi intent muestre o hable el resultado. Y puedo implementar mi método de ejecución. Al encontrar el punto más cercano, arrojaré un resultado con la entidad, el cuadro y la vista. Con el cuadro de diálogo y la vista, mis clientes siempre podrán encontrar el punto más cercano sin importar cómo se invocó la intent. Hablando de eso, crear un atajo de app para esta intent facilitará su ejecución aún más. Mis clientes ahora pueden usar Siri o Spotlight para acceder a esta intent incluso si su teléfono está en el bolsillo. Las intents, entidades y consultas son fundamentales para App Intents. Cada protocolo tiene subprotocolos y configuraciones que proporcionan mayor funcionalidad. Veamos cómo puedo mejorar mi App Entity para brindar más experiencias. Me gustaría poder ver fácilmente una foto del punto más cercano. Puedo usar la app Atajos para ayudarme. Crearé un atajo y agregaré la intent Buscar punto de referencia más cercano. Agregaré la acción Mostrar contenido para ver los resultados. Esto representará el resultado de mi intent. Por defecto, esta acción muestra la representación de la entidad, pero puedo elegir otra propiedad de entidad para renderizar.

LandmarkEntity no tiene una imagen, pero tiene una ruta hacia la imagen. Puedo usar el protocolo Transferible para declarar una imagen para la entidad. Transferible es una forma de describir diferentes representaciones de datos para un tipo. Estas representaciones permiten compartir datos entre apps. Ingresaré los datos de imagen como parte de TransferRepresentation. En Atajos, ahora puedo mostrar la representación de imagen de la entidad. Al ejecutar mi atajo, se mostrará la imagen del punto. Declarar una representación de imagen tiene beneficios extra. Puedo usar este valor de imagen como entrada para tomar fotografías, incluso desde otras apps. Para conocer más sobre Transferible, ve estas sesiones.

Quiero aplicar otro cambio a mi entidad para que sea más fácil de encontrar en el sistema. Spotlight proporciona una potente búsqueda semántica entre apps. Las entidades donantes amplían la comprensión del sistema sobre tu contenido. Para que Spotlight indexe mi entidad, puedo adoptar el protocolo IndexedEntity. Es una App Entity que incluye un conjunto de atributos de Core Spotlight.

Ahora puedes agregar claves de indexación de Spotlight en las propiedades. Anotar propiedades permite que Spotlight muestre información más relevante a tus clientes. Al donar entidades indexadas, la estructura crea el elemento de búsqueda y el conjunto de atributos por ti. Luego de donar entidades, las encontrarás en Spotlight. La app se pondrá en primer plano al tocar una entidad. Puedo mejorar esta experiencia y abrir directamente la vista de detalles del punto de referencia. Empezaré creando una intent que se ajuste al protocolo OpenIntent. Las intents que adoptan este protocolo abren la app antes de ejecutarse, por lo que no necesitas agregar un modo compatible. Las intents abiertas deben tener un parámetro target. Al tocar una entidad en Spotlight, se ejecuta una intent abierta coincidente.

En lugar de invocar mi navegador, ahora puedo adoptar el nuevo protocolo TargetContentProviderIntent, diseñado para la navegación. Estas intents no requieren un método de ejecución. En su lugar, puedo adjuntar un modificador onAppIntentExecution. En el cierre, puedo usar el parámetro para realizar una navegación SwiftUI.

Ahora, tocar un lugar desde Spotlight, me llevará directamente a la vista de detalles de este. Me gustaría finalizar esta sección explicando las consultas y cómo proporcionan entidades. Para ver esto en la práctica, crearé un nuevo atajo de app que abra un punto. Agregué un nuevo atajo a mi proveedor junto con dos frases. Una con un parámetro de punto de referencia y otra sin él. Sin embargo, al ejecutar mi atajo no veo ningún punto para elegir. Como habrás adivinado, puedo usar la consulta para ofrecer algunos puntos. Implementaré el método suggestedEntities en Entity Query, para que mis clientes puedan ver sus puntos favoritos. Ahora, al volver a ejecutar la intent, puedo ver la lista de entidades sugeridas. Las entidades sugeridas tienen otro uso. ¿Recuerdas cuando agregué una frase parametrizada? Puedo generar un atajo para cada entidad sugerida invocando el método updateAppShortcutParameters en mi proveedor. Ahora puedo usar Siri y Atajos para navegar fácil y directamente a mis puntos favoritos. Las consultas pueden responder a otras preguntas sobre tus entidades. Si todas tus entidades caben en la memoria, una EnumerableEntityQuery puede devolverlas todas. App Intents pueden obtener consultas más complicadas a partir de esta. EntityPropertyQuery permite devolver una lista ordenada de entidades, dado un conjunto de predicados. Yo aplicaré EntityStringQuery para admitir la búsqueda a partir de una cadena. Arrojaré una lista de puntos donde la cadena coincida con su nombre o descripción. Mis clientes ahora podrán buscar los resultados al configurar una intent que necesita un punto de referencia. Apenas vimos la superficie de App Intents y sus numerosas capacidades. Consulta la documentación de App Intents para ver las formas en que la estructura deleitará a tus usuarios. Me gustaría finalizar explicando la arquitectura que impulsa App Intents. Cuando creas una app con App Intents, tu código es la fuente de la verdad. App Intents no requiere archivos de configuración o instalación. El código fuente Swift se leerá durante la creación para generar su representación de App Intents. Esta representación se almacena dentro de tu app o estructura. Una vez instalada tu app, el sistema usará estos datos para comprender sus capacidades sin necesidad de ejecutarla. Veamos cómo funciona esto. El nombre de la intent se convierte en el identificador único de la acción. El título permite diferenciarla entre otras intents, y la firma de devolución del método de ejecución describe cómo representar el resultado. Dado que este proceso ocurre durante el desarrollo, y no en la ejecución, ciertos valores deben ser constantes. Por ejemplo, el título debe ser constante. Invocar una función o propiedad computarizada genera un error. Este procesamiento ocurre por cada objetivo en tu app. Para compartir correctamente los tipos de App Intent entre los objetivos, debes tener en cuenta algunas cosas. El año pasado, lanzamos la capacidad para que tu app y las extensiones de App Intents consulten los tipos de App Intent definidos en una estructura. Este año, nos complace anunciar que ahora puedes agregar App Intents a tus paquetes Swift y bibliotecas estáticas. Al usar tipos de App Intent en distintos objetivos, debes proporcionar información adicional sobre cada objetivo. Esto garantiza que tus tipos estén bien indexados y validados. Analicemos el tema para ver cómo se hace. Mi app solo tiene un objetivo con todo el código de mis App Intents. Quiero presentar una nueva extensión para alojar algunas intents. Estos objetivos necesitan acceso a Landmarks. Crearé un paquete Swift y moveré mi LandmarkEntity allí. Para compartir tipos entre objetivos, debo registrarlos como un paquete de App Intents. Primero, crearé un paquete de App Intents en el destino de la entidad. Agregaré otro paquete al objetivo de mi app. Puedo agregar una lista de paquetes, así que incluiré el que acabo de crear. Al final, haré lo mismo desde mi extensión. Esto garantiza que el entorno de ejecución de App Intents pueda acceder a los tipos definidos. Usa el paquete de App Intents cuando consultes un código no compilado en una biblioteca estática.

Es hora de concluir. Si este fue tu primer acercamiento a App Intents, comienza agregando el primer atajo a tu app. A partir de ahí, explora la estructura para ver qué puede aportar el mayor valor a tus clientes. Si quieres saber más sobre App Intents, habrá otras sesiones este año. ¡Gracias por acompañarnos!