AppIntent: 정의, Siri 인텐트 모델 및 Swift

AppIntent란 무엇이며 왜 필요한가?

AppIntent는 앱이 Siri, Shortcuts, Spotlight, Control Center 및 Action Button의 요청에 따라 실행할 수 있는 명령어를 선언적으로 설명하기 위한 Apple 프레임워크입니다. 이는 AppIntent 프로토콜을 기반으로 하며, 개발자는 인텐트 이름, 매개변수 및 perform() 메서드(실행 가능 로직)를 설명합니다. 프레임워크는 Shortcuts 앱에서 매개변수를 구성하기 위한 사용자 인터페이스와 Siri용 음성 문구를 자동 생성합니다.

AppIntent 이전에는 개발자들이 Intents framework를 사용했습니다. 이는 Intents Definition File을 기반으로 Objective-C 코드를 생성하고 별도의 Intents Extension 설정이 필요한 시스템이었습니다. 이 과정은 번거로웠으며, 간단한 인텐트조차 최대 5개의 구성 파일이 필요했습니다. AppIntent는 이러한 복잡성을 제거합니다. 인텐트는 단일 Swift 파일로 설명되고, 시스템은 Siri 및 Shortcuts와의 통합에 필요한 모든 것을 자동 생성합니다.

WWDC 2024 세션 "Dive deeper into App Intents"에 따르면, Apple은 AppIntent를 전통적인 UI를 넘어 앱 기능을 확장하는 중앙 메커니즘으로 보고 있습니다. iOS 18 출시 시점에 App Store 상위 100개 앱 중 70% 이상이 이미 Shortcuts 및 Siri와의 통합에 AppIntent를 사용하고 있으며, 평균 iOS 18 사용자는 음성 명령어나 위젯을 통해 하루에 4~6개의 인텐트를 실행합니다.

AppIntent 사용처

• Siri — 음성 명령어: "Hey Siri, MyApp에 작업 추가"
• Shortcuts — 매개변수 구성이 포함된 단축어 앱의 자동화
• Spotlight — 검색창에서 직접 검색 및 명령어 실행
• Control Center — iOS 18+의 빠른 동작 버튼
• Action Button — iPhone 15 Pro 이상의 버튼에 동작 할당

AppIntent vs Intents framework: 주요 차이점

Intents framework(iOS 10–15)는 .intentdefinition 파일 생성, Xcode를 통한 ObjC/Swift 클래스 생성, Intents Extension 및 App Intent Configuration 설정이 필요했습니다. AppIntent(iOS 16+)는 생성, 확장 또는 추가 구성 없이 순수 Swift 코드로 이 파이프라인을 완전히 대체합니다. 이는 SiriKit을 공부하지 않고도 일반 iOS 개발자가 인텐트 생성 프로세스에 접근할 수 있게 합니다.

AppIntent의 주요 장점은 선언성입니다. 개발자는 인텐트가 무엇을 하는지 설명하고, 시스템과 어떻게 통합되는지는 설명하지 않습니다. 프레임워크 자체가 Siri 대화 시나리오, Shortcuts에서의 매개변수 표시 및 인텐트 간 컨텍스트 전달을 처리합니다. 기존 Intents framework에서는 인텐트 UI 표시를 위한 INUIHostedView를 포함한 통합의 모든 측면을 수동으로 코딩해야 했습니다.

접근 방식 비교

주요 프로토콜: AppIntent, AppEntity, AppEnum

AppIntent는 인텐트를 정의하는 중앙 프로토콜입니다. title(Siri용 이름), description(Shortcuts에서의 설명), 매개변수(@Parameter를 통해) 및 IntentResult를 반환하는 perform() 메서드를 포함합니다. 결과는 IntentDialog(Siri 대화), Shortcuts에 반환할 값 또는 오류일 수 있습니다. 각 인텐트는 suggestedInvocationPhrase(음성 호출을 위한 문구)도 제공할 수 있습니다.

AppEntity는 인텐트가 작업하는 엔터티를 설명합니다. 예를 들어, 앱이 프로젝트를 관리하는 경우 AppEntity Project에는 id, displayRepresentation(UI에서 엔터티를 표시하는 방법) 및 defaultQuery(엔터티 검색 방법)가 포함됩니다. AppEnum은 선택 매개변수를 위한 열거형으로, Shortcuts에서 피커 요소가 있는 UI를 자동 생성합니다. 매개변수 목록을 수동으로 만드는 대신 AppEnum을 준수하는 enum을 선언하면 충분합니다.

AppEnum 및 매개변수 예제

enum TaskPriority: String, AppEnum {
    case low, medium, high
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Priority"
    
    var displayRepresentation: DisplayRepresentation {
        switch self {
        case .low: "Low"
        case .medium: "Medium"
        case .high: "High"
        }
    }
}

struct CreateTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Create Task"
    
    @Parameter(title: "Task Name")
    var taskName: String
    
    @Parameter(title: "Priority")
    var priority: TaskPriority
    
    func perform() async throws -> some IntentResult {
        try await TaskManager.shared
            .createTask(name: taskName, priority: priority)
        return .result(dialog: "Task created")
    }
}

인텐트 매개변수 및 유효성 검사

AppIntent의 매개변수는 @Parameter 프로퍼티 래퍼를 통해 선언되며, Shortcuts UI 및 Siri 음성 요청과 자동으로 통합됩니다. 각 매개변수에는 title(Shortcuts에 표시됨)이 있으며 설명, 기본값 및 제약 조건을 포함할 수 있습니다. AppIntent는 표준 타입(String, Int, Double, Bool)과 AppEntity 및 AppEnum을 통한 사용자 정의 타입을 지원합니다.

매개변수 유효성 검사는 로직 실행 전에 perform() 메서드에서 수행됩니다. 매개변수가 유효하지 않으면 인텐트는 IntentError를 통해 오류를 반환합니다. 복잡한 유효성 검사를 위해 perform() 전에 호출되는 validate() 메서드를 구현할 수 있으며, 명령어 실행 전에도 IntentDialog를 통해 사용자에게 피드백을 제공할 수 있습니다. 이는 잘못된 명령어를 실행하는 것보다 사용자에게 다시 묻는 것이 더 쉬운 Siri 음성 시나리오에서 특히 유용합니다.

유효성 검사가 있는 매개변수

struct SendMessageIntent: AppIntent {
    static var title: LocalizedStringResource = "Send Message"
    
    @Parameter(title: "Recipient")
    var recipient: String
    
    @Parameter(title: "Message")
    var message: String
    
    func validate() throws {
        guard message.count >= 1 else {
            throw IntentError.invalidMessage
        }
    }
    
    func perform() async throws -> some IntentResult {
        try await Messenger.shared
            .send(recipient: recipient, text: message)
        return .result(dialog: "Sent!")
    }
}

Swift에서 인텐트 생성: 예제

앱에서 메모를 검색하는 인텐트의 완전한 예제는 AppEntity 및 EntityQuery와의 작업을 보여줍니다. SearchNotesIntent는 검색 문자열을 받아 찾은 메모 목록을 반환합니다. AppEntity Note는 메모 구조를 설명하고, EntityQuery는 저장소 전체의 검색을 구현합니다. 결과는 엔터티 배열과 함께 IntentResult를 통해 반환되며, Shortcuts가 사용자에게 표시합니다.

struct Note: AppEntity {
    let id: UUID
    let title: String
    let content: String
    
    static var typeDisplayRepresentation: TypeDisplayRepresentation =
        "Note"
    
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "(title)")
    }
}

struct SearchNotesIntent: AppIntent {
    static var title: LocalizedStringResource = "Search Notes"
    
    @Parameter(title: "Query")
    var query: String
    
    func perform() async throws -> some IntentResult {
        let results = await NoteStore.shared
            .search(query)
            .map { $0.toEntity() }
        return .result(value: results)
    }
}

Shortcuts 및 Siri와의 통합

AppIntent를 선언하면 Shortcuts 및 Siri와의 통합이 자동으로 이루어집니다. Shortcuts 앱은 설치된 앱의 모든 AppIntent를 스캔하여 사용 가능한 동작 목록에 표시합니다. 사용자는 인텐트를 단축어에 추가하고, 매개변수를 구성하며, 다른 동작과 결합할 수 있습니다. Siri의 경우, 개발자의 추가 설정 없이 인텐트가 음성 명령어로 나타납니다.

개발자는 suggestedInvocationPhrase(음성 호출을 위한 권장 문구)를 추가하여 통합을 개선할 수 있습니다. 예를 들어, 작업 추가 인텐트의 경우: suggestedInvocationPhrase = "Add new task"입니다. Siri는 이 문구를 분석하여 음성 명령어 학습 시 사용자에게 제안합니다. categories(create, view, search, edit)도 지정할 수 있으며, 이는 Shortcuts가 동작을 의미별로 그룹화하는 데 도움이 됩니다.

Shortcuts용 인텐트 카테고리