AppIntent: nedir, Siri intent modeli ve Swift

AppIntent Nedir ve Neden Gereklidir?

AppIntent, uygulamanızın Siri, Shortcuts, Spotlight, Control Center ve Action Button talebiyle yürütebileceği komutları bildirimsel olarak tanımlamak için bir Apple framework'üdür. Temelinde, geliştiricinin intent adını, parametrelerini ve perform() metodu (yürütülebilir mantık) tanımladığı AppIntent protokolü bulunur. Framework, Shortcuts uygulamasında parametreleri yapılandırmak için otomatik olarak bir kullanıcı arayüzü ve Siri için sesli ifadeler oluşturur.

AppIntent'ten önce geliştiriciler, Intents Definition File'a dayalı, Objective-C kodu oluşturan ve ayrı bir Intents Extension yapılandırması gerektiren Intents framework'ünü kullanıyordu. Bu süreç zahmetliydi: basit bir intent bile 5 yapılandırma dosyası gerektiriyordu. AppIntent bu karmaşıklığı ortadan kaldırır — bir intent tek bir Swift dosyasında tanımlanır ve sistem, Siri ve Shortcuts ile entegrasyon için gereken her şeyi otomatik olarak oluşturur.

WWDC 2024 Oturumu "Dive deeper into App Intents"'e göre Apple, AppIntent'i geleneksel kullanıcı arayüzünün ötesinde uygulama işlevselliğini genişletmek için merkezi mekanizma olarak görmektedir. iOS 18'in piyasaya sürüldüğü sırada, App Store ilk 100'ündeki uygulamaların %70'inden fazlası Shortcuts ve Siri ile entegrasyon için AppIntent'i kullanmaktadır ve ortalama bir iOS 18 kullanıcısı sesli komutlar veya widget'lar aracılığıyla günde 4-6 intent başlatmaktadır.

AppIntent Nerelerde Kullanılır

• Siri — sesli komutlar: "Hey Siri, MyApp'e bir görev ekle"
• Shortcuts — parametre yapılandırmasıyla Kısayollar uygulamasında otomasyon
• Spotlight — arama çubuğundan doğrudan arama ve komut yürütme
• Control Center — iOS 18+'da hızlı eylem düğmeleri
• Action Button — iPhone 15 Pro ve sonrasının düğmesine eylem atama

AppIntent vs Intents framework: Temel Farklar

Intents framework (iOS 10–15), .intentdefinition dosyası oluşturma, Xcode aracılığıyla ObjC/Swift sınıfları oluşturma, Intents Extension ve App Intent Configuration yapılandırması gerektiriyordu. AppIntent (iOS 16+), bu ardışık düzeni oluşturma, uzantı veya ek yapılandırma olmadan tamamen saf Swift koduyla değiştirir. Bu, SiriKit'i öğrenmeden ortalama bir iOS geliştiricisinin intent oluşturma sürecine erişmesini sağlar.

AppIntent'in temel avantajı bildirimsel olmasıdır. Geliştirici, intent'in ne yaptığını tanımlar, sisteme nasıl entegre olduğunu değil. Framework'ün kendisi Siri diyalog senaryolarını, Shortcuts'ta parametre görüntülemeyi ve intent'ler arasında bağlam aktarımını yönetir. Eski Intents framework'ünde, intent kullanıcı arayüzünü görüntülemek için INUIHostedView dahil olmak üzere entegrasyonun her yönü manuel olarak kodlanmalıydı.

Yaklaşımların Karşılaştırması

Temel Protokoller: AppIntent, AppEntity, AppEnum

AppIntent, bir intent'i tanımlayan merkezi protokoldür. Bir title (Siri için ad), description (Shortcuts'ta açıklama), parametreler (@Parameter aracılığıyla) ve IntentResult döndüren perform() metodu içerir. Sonuç, IntentDialog (Siri diyalogu), Shortcuts'a döndürülecek bir değer veya bir hata olabilir. Her intent ayrıca suggestedInvocationPhrase — sesli çağrı için bir ifade sağlayabilir.

AppEntity, intent'lerin çalıştığı varlıkları tanımlar. Örneğin, bir uygulama projeleri yönetiyorsa, AppEntity Project, id, displayRepresentation (varlığın kullanıcı arayüzünde nasıl görüntüleneceği) ve defaultQuery (varlıkların nasıl aranacağı) içerir. AppEnum, Shortcuts'ta seçici öğe ile otomatik olarak kullanıcı arayüzü oluşturan seçim parametreleri için bir numaralandırmadır. Parametre listesini manuel olarak oluşturmak yerine, AppEnum'a uygun bir enum bildirmek yeterlidir.

AppEnum ve Parametre Örneği

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")
    }
}

Intent Parametreleri ve Doğrulama

AppIntent parametreleri, Shortcuts kullanıcı arayüzü ve Siri sesli istekleriyle otomatik olarak entegre olan @Parameter özellik sarmalayıcısı aracılığıyla bildirilir. Her parametrenin bir title'ı (Shortcuts'ta görüntülenir) vardır ve bir açıklama, varsayılan değerler ve kısıtlamalar içerebilir. AppIntent standart türleri destekler: String, Int, Double, Bool ve AppEntity ile AppEnum aracılığıyla özel türler.

Parametre doğrulaması, mantık yürütülmeden önce perform() metodunda gerçekleştirilir. Parametreler geçersizse, intent IntentError aracılığıyla bir hata döndürür. Karmaşık doğrulama için, perform()'den önce çağrılan validate() metodu uygulanabilir ve komutu yürütmeden önce bile IntentDialog aracılığıyla kullanıcıya geri bildirim sağlayabilir. Bu, yanlış bir komutu yürütmektense kullanıcıya tekrar sormanın daha kolay olduğu Siri sesli senaryoları için özellikle kullanışlıdır.

Doğrulamalı Parametreler

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'te Intent Oluşturma: Örnek

Bir uygulamada not aramak için intent'in tam bir örneği, AppEntity ve EntityQuery ile çalışmayı gösterir. SearchNotesIntent bir arama dizesi alır ve bulunan notların listesini döndürür. AppEntity Note not yapısını tanımlar ve EntityQuery depolamada aramayı uygular. Sonuç, Shortcuts'ın kullanıcıya gösterdiği varlık dizisiyle IntentResult aracılığıyla döndürülür.

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 ve Siri ile Entegrasyon

Bir AppIntent bildirildikten sonra, Shortcuts ve Siri ile entegrasyon otomatik olarak gerçekleşir. Shortcuts uygulaması, yüklü uygulamalardaki tüm AppIntent'leri tarar ve bunları mevcut eylemler listesinde görüntüler. Kullanıcı, intent'ini kısayoluna ekleyebilir, parametrelerini yapılandırabilir ve diğer eylemlerle birleştirebilir. Siri için intent'ler, geliştiricinin ek yapılandırması olmadan sesli komutlar olarak görünür.

Geliştirici, suggestedInvocationPhrase (sesli çağrı için önerilen ifade) ekleyerek entegrasyonu iyileştirebilir. Örneğin, görev ekleme intent'i için: suggestedInvocationPhrase = "Add new task". Siri bu ifadeyi analiz eder ve sesli komutları öğrenirken kullanıcıya önerir. Ayrıca categories (create, view, search, edit) belirtilebilir, bu da Shortcuts'ın eylemleri anlamlarına göre gruplandırmasına yardımcı olur.

Shortcuts için Intent Kategorileri