Intents Extension: conceptos clave e integración de Siri Intents en iOS

Qué es Intents Extension en iOS

Intents Extension es una extensión de aplicación que permite a Siri, Shortcuts y otros servicios del sistema invocar funcionalidades de la aplicación a través del protocolo estandarizado INIntentHandler. Cuando un usuario dice “Oye Siri, envía un mensaje en Messenger X”, Siri activa la extensión correspondiente, pasa los parámetros de la solicitud y recibe el resultado para verbalizarlo.

A diferencia de otros tipos de extensiones, Intents Extension funciona en segundo plano sin una interfaz visible: Siri muestra la respuesta mediante voz o una tarjeta de texto. La extensión puede proporcionar opcionalmente una interfaz personalizada a través de INUIHostedViewProviding, que se muestra dentro de Siri antes de ejecutar un comando para su confirmación.

La extensión no tiene acceso a la pantalla del dispositivo y no puede iniciar acciones por sí misma, solo en respuesta a una solicitud de Siri o Shortcuts. Esto garantiza la seguridad: el usuario siempre controla qué acciones realiza la aplicación mediante comandos de voz.

SiriKit y dominios de intents

SiriKit es el framework de Apple para la integración con Siri, presentado en iOS 10. Define dominios, categorías de acciones que Siri puede manejar: mensajes, llamadas telefónicas, pagos, listas, recordatorios, fotos, entrenamientos, reservas y otros. Cada dominio tiene un conjunto fijo de intents y respuestas.

Dominios estándar

INSendMessageIntent — envío de mensajes. INStartWorkoutIntent — inicio de entrenamiento. INSearchForPhotosIntent — búsqueda de fotos. INRequestRideIntent — solicitud de viaje. Cada dominio define parámetros obligatorios y opcionales que Siri extrae de la solicitud de voz. Según Apple, los dominios estándar no requieren un archivo intentdefinition; basta con implementar el controlador correspondiente.

Para las aplicaciones que no encajan en los dominios estándar, iOS 14 introdujo la capacidad de usar intents personalizados. La aplicación define sus propios tipos de comandos y sus parámetros a través de Intents.intentdefinition, y Siri aprende a reconocer las frases correspondientes basándose en ejemplos proporcionados por el desarrollador.

Configuración en Info.plist

Intents Extension se registra mediante la clave IntentsSupported en Info.plist, que enumera todas las clases de intents que maneja la extensión. Siri usa esta lista para seleccionar la extensión adecuada al reconocer un comando de voz. Si varias extensiones admiten el mismo intent, Siri solicita al usuario que elija.

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

    func handle(
        intent: INSendMessageIntent,
        completion: @escaping
            (INSendMessageIntentResponse) -> Void
    ) {
        let response = INSendMessageIntentResponse(
            code: .success, userActivity: nil)
        completion(response)
    }
}

INIntentHandler: procesamiento de solicitudes

INIntentHandler es un protocolo que define métodos para manejar cada etapa del procesamiento de intents: resolución de parámetros, confirmación y ejecución. La extensión implementa estos métodos para cada tipo de intent que admite.

Tres etapas de procesamiento

resolve — validación y aclaración de los parámetros del intent. Siri llama a este método para cada parámetro. Si falta un parámetro o es incorrecto, la extensión devuelve una solicitud de aclaración y Siri le hace una pregunta adicional al usuario. confirm — confirmación de la intención. La extensión verifica si puede ejecutar el intent en el contexto actual. handle — ejecución real de la operación y devolución del resultado.

La separación en tres etapas es fundamental para la experiencia de usuario por voz: si no se reconoce un parámetro, Siri no ejecuta la acción sino que pide una aclaración. Por ejemplo, si el usuario dijo “Envía un mensaje a Alex” pero hay tres Alex en los contactos, la extensión devuelve un resolve con una solicitud de aclaración y Siri pregunta “¿Cuál Alex?”

INIntentResponse y códigos de estado

INIntentResponse es un objeto que la extensión devuelve en el controlador de finalización después de ejecutar el intent. La respuesta contiene un código de resultado (success, failure, requiresAuthentication, inProgress) y datos opcionales para que Siri los verbalice. El código determina cómo responde Siri: success — confirmación por voz, failure — mensaje de error, inProgress — indicación de una operación prolongada.

func resolve(
    for intent: INSendMessageIntent,
    with completion: @escaping
        (INStringResolutionResult) -> Void
) {
    if let text = intent.content, !text.isEmpty {
        completion(.success(with: text))
    } else {
        completion(.needsValue())
    }
}

Creación de intents personalizados

Con iOS 14, los desarrolladores obtuvieron la capacidad de definir intents personalizados fuera de los dominios estándar de SiriKit. Los intents personalizados se describen en el archivo Intents.intentdefinition, un editor visual dentro de Xcode donde se crean nuevos tipos de comandos con parámetros y respuestas.

Estructura del intent personalizado

Cada intent personalizado consta de INIntent (definición de la solicitud) y INIntentResponse (definición de la respuesta). INIntent contiene parámetros con tipos de datos: String, Integer, CurrencyAmount, objetos encontrados y otros. INIntentResponse contiene propiedades para devolver resultados y una matriz de códigos de respuesta. Xcode genera automáticamente clases de Swift basadas en esta definición.

Apple recomienda incluir no más de 5 parámetros en un intent personalizado: el exceso de parámetros degrada el reconocimiento de voz y complica la experiencia del usuario. Para cada parámetro, es recomendable proporcionar frases de ejemplo en el Diálogo de Asistente para que Siri aprenda a reconocerlas correctamente.

Frases de ejemplo para Siri

En Intents.intentdefinition, para cada intent puede especificar oraciones de ejemplo: frases que el usuario dirá a Siri para activar el intent. Ejemplos: “Pide café en MiApp”, “Pide a MiApp que encuentre una receta de pizza”. Siri usa estas frases para entrenar el reconocimiento y las sugiere al usuario al configurar Shortcuts.

// Intents.intentdefinition (editor visual)
Intent: OrderCoffeeIntent
Parameters:
  - beverage (String)
  - size (String)
  - quantity (Integer)
Response:
  - orderNumber (String)
  - price (CurrencyAmount)
Phrases:
  - "Order coffee in MyApp"
  - "Get a latte from MyApp"

Interacción por voz y INUIHostedViewProviding

INUIHostedViewProviding es un protocolo que permite a Intents Extension mostrar una interfaz personalizada dentro de Siri antes de ejecutar un comando. Por ejemplo, al solicitar un viaje, la extensión puede mostrar un mapa con la ruta y el costo, y el usuario confirma la acción tocando.

Configuración de la interfaz

El protocolo define el método configure(with:for:completion:), donde la extensión recibe el intent y devuelve un UIViewController que se incrustará en Siri. El tamaño del controlador está limitado: altura máxima 200 puntos. Se recomienda usar tarjetas compactas con información clave: importe, hora, dirección.

La interfaz personalizada es opcional: si la extensión no implementa INUIHostedViewProviding, Siri muestra una tarjeta estándar con el tipo de intent y el nombre de la aplicación. Para la mayoría de los intents, la interfaz de usuario estándar es suficiente, y Apple recomienda agregar una interfaz personalizada solo cuando realmente mejore la comprensión, por ejemplo, para mostrar una ruta o confirmar un pago.

Seguridad y confirmación

Para los intents relacionados con finanzas o datos personales, se requiere autenticación. INIntentResponse admite el código requiresAuthentication, que obliga a Siri a solicitar Face ID o Touch ID antes de la ejecución. Después de la autenticación, la extensión recibe la confirmación a través de una llamada handle separada, donde se verifica el estado de autenticación.

Apple enfatiza específicamente: Intents Extension no debe solicitar su propia contraseña o datos biométricos; se utiliza la autenticación del sistema. Almacenar tokens de acceso en Keychain con acceso compartido entre la aplicación y la extensión es una práctica estándar para sesiones de larga duración.

class IntentViewController: UIViewController {

    func configure(
        with intent: INIntent,
        completion: @escaping
            (UIViewController?) -> Void
    ) {
        let cardView = ConfirmationCardView()
        let hostingController =
            UIHostingController(rootView: cardView)
        completion(hostingController)
    }
}