Desarrolla para Atajos y Spotlight con App Intents

Hola, soy Ayaka y formo parte del equipo de Atajos. Te doy la bienvenida a Desarrolla para Atajos y Spotlight con App Intents. App Intents da más visibilidad a tu app al permitir usar funciones clave en entornos como Atajos y Spotlight. La app Atajos conecta apps y acciones, para que el día a día sea más rápido y fluido. Puedes usar Atajos para automatizar tareas y conectarte a otras funciones de distintas apps. Por ejemplo, para guardar una receta de Safari en una nota de la app Notas. Este año, incorporamos Apple Intelligence a Atajos para que combinar acciones sea fácil y divertido. También puedes ejecutar acciones de Atajos, incluso de tu app, directamente desde Spotlight en la Mac. Veremos cómo puedes adoptar App Intents para que tu app funcione con Atajos y Spotlight. Comenzaremos con la acción Usar modelo, que permite usar modelos de Apple Intelligence en Atajos. Veremos cómo funciona, junto con formas de ejecutar Atajos desde Spotlight y Automatizaciones en la Mac. Comencemos. Esta es la nueva acción Usar modelo. Es una de las acciones inteligentes que agregamos a Atajos este año. Además de acciones para Image Playground, herramientas de escritura y más. Con esta acción, las tareas tediosas, como analizar texto o formatear datos, ahora necesitan que escribas pocas palabras. Puedes usar un modelo avanzado en Private Cloud Compute para solicitudes complejas con privacidad, o uno en el dispositivo para tareas simples sin conexión. También puedes usar ChatGPT si quieres aprovechar su conocimiento y experiencia. Puedes usar un modelo para filtrar eventos de calendario, resumir contenido web o conocer lo último de la gastronomía con ChatGPT. Este es un ejemplo de atajo con un modelo. Es uno simple que me permite organizar las notas del trabajo. Primero obtiene las notas de hoy, le pregunta al modelo si están relacionadas con el proyecto y, si la respuesta es sí, las guarda en mi carpeta de proyectos. Como uso la salida del modelo con una acción “si”, que espera un valor booleano, el sistema genera ese tipo de salida. En lugar de devolver texto largo, el modelo responde con un sí o no en formato booleano, que puedo usar en la acción “si”. Si quieres más control, puedes elegir uno de estos tipos de salida integrados. Puedes hacer esto al probar una acción en un flujo, antes de decidir a qué conectar su salida. Hoy veremos Texto, Diccionario y Contenido de tus apps, y cómo hacer para que la salida del modelo funcione bien con la entrada de tu app. Empecemos con Texto. El texto es el sustento de los modelos de lenguaje. A primera vista, parece la opción más simple, pero en realidad tiene mucha complejidad y riqueza. Literalmente. Esto se debe a que los modelos a menudo responden con Texto enriquecido. Algunas partes de la respuesta pueden estar en negrita o cursiva. Incluso puede tener una lista o tabla como esta. Si tu app admite texto enriquecido, asegúrate de usar cadenas con atributos en los parámetros de texto de tus intents. Una cadena con atributos combina caracteres, rangos y un diccionario para definir cómo se muestra el texto. Al admitir cadenas con atributos, la salida del modelo se integra en tu app. Veámoslo en acción. Este es un atajo que usa ChatGPT para crear una plantilla de entrada de diario que uso en la app Bear. Le pido al modelo una tabla para registrar el estado de ánimo en la mañana, tarde y noche, y espacio para notas destacadas del día. Luego, el atajo toma la salida del modelo y la pasa a la acción Crear nota de la app Bear. Lo voy a ejecutar para mostrar cómo funciona.

Aquí está mi entrada de diario de hoy. Tiene formato de texto enriquecido, como poner en negrita lo importante, y la tabla de registro que solicité. ¿Notas destacadas del día? ¿Qué tal “grabé la charla de la WWDC”?

Terminaré esta entrada más tarde. Como la app Bear admite cadenas con atributos, pudo mostrar sin pérdidas el texto enriquecido generado por el modelo.

Para obtener más información sobre cómo admitir cadenas con atributos, consulta “Novedades en Foundation” y “Code-along”. Ahora veamos Diccionario. El tipo de salida Diccionario es útil cuando quieres que una solicitud te devuelva datos en formato estructurado. Puedes crear un atajo que revise todos los archivos de una carpeta, extraiga información de cada elemento y la agregue en una hoja de cálculo. Para esto, puedo usar el modelo para extraer la información y decir cómo quiero que se formatee el diccionario de salida. Puedo usar los valores del diccionario en otras acciones, como agregar una fila. Con estos modelos, puedo tomar datos no estructurados, como los de un PDF y transformarlos en la estructura necesaria para conectarlos a otra acción. Por último, veamos Contenido en tus apps. El contenido de tus apps se representa como entidades definidas con la estructura de App Intents. Por ejemplo, una app de calendario brinda entidades para calendarios y eventos. Si las App Intents son las acciones o verbos, las App Entities son los sustantivos. Puedes pasar App Entities al modelo. Si incluyes en la solicitud una lista de entidades, te mostrará una opción adicional: el tipo de App Entity que enviaste. Si le paso al modelo una lista de eventos, puedo pedirle que filtre y solo deje los de mi viaje. La acción le pasa al modelo una representación JSON de tu entidad, así que debes incluir en su definición toda la información que deba usar. Todas las propiedades expuestas a Atajos pasarán a texto y se incluirán en el JSON. El nombre en typeDisplayRepresentation también se incluye, para que el modelo sepa qué representa la entidad, como un evento del calendario. Se agregarán título y subtítulo definidos en displayRepresentation de la entidad. Veamos un ejemplo.

En la representación simplificada de un evento se incluirán el título, la fecha de inicio y fin, el nombre del tipo, y el título y subtítulo definidos en displayRepresentation. Estas cadenas también se muestran en la app Atajos al inspeccionar propiedades de una entidad que se pasa a otra acción, así que hay que asegurarse de que se vean bien. Ahora que vimos cómo estructurar las entidades, veamos cómo hacer para que puedan enviarse al modelo. En este caso, pasar la entidades de calendario a filtrar. En Atajos, la forma más común es con la acción Find. Este tipo de acción permite obtener entidades de tu app con propiedades como filtros, como la fecha de inicio o el calendario. Puedes crear una acción Find con tus propias consultas con los protocolos EnumerableEntityQuery y EntityPropertyQuery. O si ya donas tus entidades a Core Spotlight con IndexedEntity, puedes usar nuevas API para vincular las propiedades de tu entidad con las claves de Spotlight y crear una acción de búsqueda. Veamos de nuevo el ejemplo de entidad de evento. Aquí, EventEntity ya adopta el protocolo IndexedEntity. El título, subtítulo e imagen de la representación visible se asocian automáticamente con sus claves en Spotlight.

Para vincular otras propiedades de tu entidad, puedes usar el nuevo parámetro indexingKey. Aquí la propiedad título del evento se asocia con la clave de título de evento en Spotlight.

Hay algunos casos en los que no hay una clave de atributo correspondiente. Puedes usar el parámetro de clave de indexación personalizada en la propiedad, como hice con la propiedad notes. Esta es la acción Find que verás en Atajos a partir de esa entidad indexada. También puedes ver como ejemplo la App Intents Travel Tracking en “developer.apple.com”. Eso es todo lo que debes saber para estructurar tus entidades y entregárselas al modelo. Ahora, veamos otra cosa que puedes hacer con la acción Usar modelo. Esta acción tiene la opción de “dar seguimiento” a la solicitud, para ajustar la respuesta con el modelo antes de pasar a la siguiente acción. Te muestro cómo la uso yo: Como quiero cocinar más, tengo un atajo que saca los ingredientes de una receta y los agrega a mi lista de compras en Things. Al activar el seguimiento, puedo seguir mi petición inicial y hacer ajustes. Puedo pedir al modelo que modifique la receta antes de guardar los ingredientes. Vamos a Safari a ver una receta de pizza. Es una receta que me compartió un amigo. Se ve muy buena. Ejecuto mi atajo para guardar los ingredientes en mi lista de compras.

Necesito 400 g de harina 00. Perfecto, se ve bien. Voy a hacer una fiesta, así que quiero preparar un poco más.

Por el seguimiento, aparece un campo de texto. Voy a solicitar: “Duplicar la receta”.

Ahora necesito 800 g de harina 00 200 g de harina integral. Bien, se ve perfecto.

Ahí están los ingredientes para mi fiesta, listos en Things. Esa es la nueva acción Usar modelo. Ahora veamos Spotlight en la Mac.

Spotlight te permite buscar apps y documentos en todo el sistema. Ya puedes ejecutar acciones de tu app directamente desde Spotlight en la Mac. Tus apps pueden mostrar acciones en Spotlight adoptando App Intents, como haces para Atajos. Las buenas prácticas de Atajos también aplican a Spotlight, como escribir un buen resumen de parámetros. Un resumen de parámetros describe en lenguaje natural qué hace la intent y qué necesita para ejecutarse.

Ese mismo resumen aparece en el editor de Atajos cuando creas un atajo. Spotlight se trata de hacer cosas rápido. Para hacer eso, la gente debe brindar la información que tu intent necesita directamente desde Spotlight. Veamos cómo lograrlo: Primero, el resumen debe tener todos los parámetros obligatorios sin valor predeterminado, ya que se mostrarán en Spotlight IU. Si tu intent no tiene parámetros así, no hace falta un resumen de parámetros. Spotlight puede mostrar el título de la intent como alternativa. Segundo, debes asegurarte de que la intención no se oculta a los atajos en Spotlight. Por ejemplo, al configurar “is discoverable” en false o “assistant only” en true en la implementación de la intent. Si adoptaste una intent para configurar widgets sin método perform, tampoco se verá en Spotlight. Veamos unos ejemplos:

Tengo una intent “CreateEventIntent” que permite crear un nuevo evento. Tiene tres parámetros, título, fecha de inicio y de finalización. Esta intent se verá en Spotlight porque todos los parámetros obligatorios están en el resumen. Pero si agrego un parámetro obligatorio Notes sin valor y no lo incluyo en el resumen, la intent no aparecerá en Spotlight. Si actualizo el parámetro Notes para que sea opcional, la intent volverá a aparecer.

También podría mantener el parámetro requerido y brindar un valor por defecto, como una cadena vacía.

Para buenas prácticas sobre resúmenes de parámetros, como elegir qué hacer opcional, mira el video “Diseña App Intents para experiencias del sistema”. Una vez que tu intent aparece en Spotlight, optimiza la experiencia de uso. Incluye sugerencias de soporte, búsqueda por escritura y opciones de ejecución en segundo y en primer plano. Veamos cómo. Al buscar y seleccionar tu intent en Spotlight, la persona debe brindar los parámetros obligatorios antes de ejecutarlo. Para que esto sea rápido, debes brindar sugerencias sobre cómo completar estos parámetros. Hay un par de protocolos que puedes implementar para hacerlo.

Puedes implementar suggestedEntities con el protocolo EntityQuery o todas las entidades con EnumerableEntityQuery. Usa suggestedEntities cuando quieras ofrecer un subconjunto de una lista, como los eventos del día siguiente en vez de todos los pasados y presentes. Todas las entidades son buenas si la lista es más pequeña y limitada, como una lista de zonas horarias. También puedes etiquetar contenido en pantalla con appEntityIdentifier en NSUserActivity para ofrecer sugerencias según el contenido. Por ejemplo, la vista detallada de un evento de calendario específico. Para más detalles, mira la sesión “Explorar avances en App Intents”. Tu intent puede adoptar el protocolo PredictableIntent para que Spotlight sugiera según su uso. Ahora consideremos la experiencia cuando alguien escribe en un campo de parámetros. Si implementaste sugerencias, tendrás automáticamente una función de búsqueda y filtrado para las sugerencias dadas. Pero si hay más entidades además de las sugeridas, debes agregar soporte de búsqueda avanzada con consultas.

Puedes implementar el protocolo EntityStringQuery o implementar IndexedEntity, como vimos. Puedes encontrar un ejemplo en App Intents Sample Code disponible en “developer.apple.com”. Para detalles sobre Indexed Entity, consulta la charla “Novedades en App Intents” de 2024. Ahora consideremos la experiencia de ejecutar la acción. Al crear un evento, a veces es mejor que la acción corra en segundo plano, pero en otros casos es útil verlo en la app. Para ofrecer ambas experiencias, puedes separar tus intents en segundo y primer plano. Una intent “crear evento” puede ser de segundo plano, para crear eventos sin abrir la app. También una intent “abrir evento” que lleve la app al primer plano abriendo un evento, una acción útil por sí misma. Luego, podemos sincronizarlos haciendo que el de segundo plano devuelva el de primer plano como Opens Intent. En este caso, el Create Event Intent puede devolver un Open Event Intent como Opens Intent. Para más detalles sobre esto, consulta el video “Explora App Intents”. Esto es Spotlight en la Mac. Ahora centrémonos en las automatizaciones. Agregamos automatizaciones a la Mac, con automatizaciones de carpetas y unidades externas, además de las de iOS, como hora del día y Bluetooth. Ahora puedo hacer que mi atajo se ejecute automáticamente al agregar algo a una carpeta, en lugar de hacerlo manualmente. Siempre que tu intent esté disponible en macOS, también se podrá usar en Atajos como automatización en la Mac. Esto incluye apps de iOS que se pueden instalar en macOS.

Eso suma Spotlight y Automatizaciones en la Mac a las formas de ejecutar Atajos, como el botón de acción, el centro de control y más. Con nuevas acciones inteligentes como Usar modelo, las posibilidades de uso de las acciones de tu app son infinitas. Terminemos con algunos próximos pasos. Primero, expón contenido de tu app como entidades compatibles con Atajos, incluida la acción Usar modelo. Eso implica ofrecer acciones de búsqueda y asegurarte de que las entidades expongan propiedades que el modelo pueda usar. Luego, usa cadenas con atributos para permitir texto enriquecido en tu app, como vimos en la demo de Bear. Por último, optimiza tus intents para Spotlight en la Mac y verifica que también se vean bien en Atajos. Gracias por acompañarnos.