App Intents: exponer tu app a Siri, Atajos y Spotlight

Hay una forma equivocada de entender App Intents que consiste en verlo como un adaptador para Siri, y produce implementaciones tristes: dos o tres acciones sueltas, mal nombradas, que abren la app y ya. La forma exacta es otra. App Intents es el mecanismo por el que una app publica su modelo de dominio en un formato que el sistema entiende: los verbos que sabe ejecutar, los sustantivos sobre los que opera, cómo se buscan esos sustantivos y qué información falta para actuar. Una vez publicado, ese vocabulario no lo consume un cliente sino muchos —el asistente, la app de Atajos, la búsqueda, el botón de acción, los widgets, los controles del sistema, la automatización— y ninguno de ellos necesita saber que tu app existe como interfaz.

Acciones, entidades y consultas

El modelo tiene tres piezas y confundirlas produce integraciones que funcionan en la demo y fallan con datos reales. Una acción es un tipo que conforma AppIntent: tiene título, parámetros y un método que hace el trabajo. Una entidad es un tipo que conforma AppEntity: representa una cosa de tu dominio con identidad estable y una representación mostrable. Y una consulta es el tipo que conforma EntityQuery y sabe encontrar entidades por identificador, por texto o devolviendo las sugeridas. Sin consulta, el sistema puede ejecutar tu acción pero no puede ayudar a la persona a elegir sobre qué.

struct Nota: AppEntity {
    let id: UUID
    let titulo: String

    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Nota"
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(titulo)")
    }
    static let defaultQuery = ConsultaNotas()
}

struct ConsultaNotas: EntityStringQuery {
    func entities(for ids: [UUID]) async throws -> [Nota] {
        await Almacen.compartido.notas(ids: ids)
    }
    func entities(matching cadena: String) async throws -> [Nota] {
        await Almacen.compartido.buscarNotas(cadena)
    }
    func suggestedEntities() async throws -> [Nota] {
        await Almacen.compartido.notasRecientes(limite: 5)
    }
}

El identificador es la pieza crítica y la que más veces se elige mal. Debe ser estable en el tiempo y único, porque el sistema lo persiste dentro de los atajos que la gente construye: un atajo que dice archivar la nota de la reunión guarda ese identificador, no el título. Usar el título, un índice de posición o un identificador de objeto de base de datos que cambie al migrar significa que los atajos del usuario dejarán de funcionar sin aviso alguno.

Las enumeraciones de dominio tienen su propia conformidad, AppEnum, y merecen un comentario porque son la vía más barata de subir la calidad de una integración. Un parámetro de tipo cadena obliga a la persona a escribir; un parámetro con enumeración le ofrece una lista, se traduce solo y admite sinónimos hablados. Casi siempre que aparece una cadena en la firma de un intent hay una enumeración mal modelada debajo.

Parámetros, resolución y diálogo

Un intent no se ejecuta hasta que todos sus parámetros requeridos tienen valor, y el proceso de conseguirlos es un protocolo, no una comprobación. Si falta un valor, el sistema lo pide. Si hay varios candidatos, desambigua. Si la acción es destructiva o costosa, conviene exigir confirmación explícita. Y todo eso ocurre sin tu interfaz, de modo que los textos que escribes en los parámetros son literalmente lo que la persona verá y oirá.

struct ArchivarNota: AppIntent {
    static let title: LocalizedStringResource = "Archivar nota"
    static let description = IntentDescription("Mueve una nota al archivo.")
    static let isDiscoverable = true

    @Parameter(title: "Nota")
    var nota: Nota

    @Parameter(title: "Avisar al terminar", default: false)
    var avisar: Bool

    static var parameterSummary: some ParameterSummary {
        Summary("Archivar \(\.$nota)") {
            \.$avisar
        }
    }

    func perform() async throws -> some IntentResult & ProvidesDialog {
        try await Almacen.compartido.archivar(nota.id)
        return .result(dialog: "He archivado \(nota.titulo)")
    }
}

El resumen de parámetros define cómo se lee la acción como una frase dentro de la app de Atajos: lo esencial va en la línea principal y lo accesorio queda plegado. Es la diferencia entre una tarjeta que se entiende de un vistazo y un formulario con seis campos. Y el diálogo devuelto es lo que el sistema dice en voz alta o muestra al terminar; puede acompañarse de una vista breve como fragmento visual cuando el resultado se entiende mejor viéndolo que oyéndolo.

Dónde aparece todo esto

La misma declaración alimenta superficies muy distintas y cada una impone matices. En la app de Atajos, cada intent descubrible es un bloque componible cuyo resultado puede alimentar al siguiente, lo que exige devolver valores tipados y no solo efectos. En Siri y en la búsqueda del sistema, lo que se invoca son atajos con frase, declarados en un proveedor específico, y ahí la calidad de la frase decide si funciona o no. En el botón de acción y en los controles del sistema, la acción debe poder ejecutarse sin ninguna pregunta. Y en la configuración de widgets, el intent deja de ser una acción para convertirse en la descripción tipada de las opciones del usuario.

struct Atajos: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: ArchivarNota(),
            phrases: ["Archiva una nota en \(.applicationName)",
                      "Guarda esto en \(.applicationName)"],
            shortTitle: "Archivar nota",
            systemImageName: "archivebox"
        )
    }
}

Las frases tienen dos reglas que no admiten excepción: deben incluir el marcador del nombre de la aplicación, porque sin él el sistema no sabe a quién dirigir la petición, y deben estar traducidas en cada idioma que soportes mediante el catálogo de cadenas específico de atajos. Una frase traducida literalmente del inglés suele ser justo la que nadie diría en voz alta; conviene escribir varias variantes por idioma, incluidas las coloquiales.

flowchart TB
a[Modelo de dominio de tu app] --> b[Acciones que conforman AppIntent]
a --> c[Entidades con identidad estable]
c --> d[Consultas por id texto y sugerencias]
b --> e[App de Atajos y automatizaciones]
b --> f[Siri y frases del proveedor]
b --> g[Spotlight y boton de accion]
b --> h[Botones y toggles del widget]
b --> i[Controles del sistema]
d --> e
d --> f

Reglas que evitan romper lo que la gente construyó

La primera es de estabilidad. El nombre del tipo, los nombres de sus parámetros y los identificadores de las entidades forman parte del contrato persistido en los atajos de los usuarios. Renombrar un tipo de Swift es una refactorización inocua en cualquier otro contexto y aquí equivale a borrar una API pública: los atajos que lo usaban aparecen rotos. Cuando haya que evolucionar, se añade en lugar de sustituir, y se marca lo viejo como no descubrible antes de retirarlo.

La segunda es de granularidad. Un intent debe representar una intención completa del usuario, no un paso interno de tu implementación. Exponer diez acciones que solo tienen sentido encadenadas en un orden concreto produce una integración inservible; exponer tres que cada una resuelve algo por sí sola produce una que la gente compone de formas que no habías previsto, que es justo el objetivo.

La tercera es de comportamiento. Todo intent puede ejecutarse desde una automatización, a las tres de la mañana, sin nadie mirando, y puede repetirse. Debe ser idempotente donde tenga sentido, debe fallar con errores descriptivos —los que conforman el protocolo de error mostrable llegan traducidos a la persona— y no debe asumir jamás que hay interfaz disponible, ni red, ni sesión iniciada.

enum ErrorNotas: Error, CustomLocalizedStringResourceConvertible {
    case sinSesion
    var localizedStringResource: LocalizedStringResource {
        "Inicia sesion en la app para archivar notas"
    }
}

Queda una cuarta regla, más difícil de cumplir que las tres anteriores: los textos son producto. El título de la acción, el título de cada parámetro, la descripción, el diálogo de respuesta y las frases no son cadenas de configuración sino la interfaz completa cuando no hay pantalla. Escribirlos con la misma exigencia que se aplica a la interfaz visible es lo que distingue una integración que la gente usa a diario de una que se prueba una vez y se olvida.