AppIntent: bu nədir, Siri intent modeli və Swift

AppIntent nədir və nəyə lazımdır?

AppIntent — tətbiqinizin Siri, Shortcuts, Spotlight, Control Center və Action Button vasitəsilə yerinə yetirə biləcəyi əmrləri deklarativ şəkildə təsvir etmək üçün Apple çərçivəsi. Əsasında AppIntent protokolu dayanır, orada tərtibatçı intentin adını, parametrlərini və perform() metodunu — yerinə yetirilən məntiqi təsvir edir. Çərçivə avtomatik olaraq Shortcuts tətbiqində parametrlərin konfiqurasiyası üçün istifadəçi interfeysi və Siri üçün səs frazalarını yaradır.

AppIntent yaranana qədər tərtibatçılar Intents framework-dən istifadə edirdilər — Intent Definition File əsaslı sistem, Objective-C kodu yaradır və ayrıca Intents Extension konfiqurasiyası tələb edirdi. Bu proses çətin idi: hətta sadə bir intent 5 konfiqurasiya faylı tələb edirdi. AppIntent bu mürəkkəbliyi aradan qaldırır — intent bir Swift faylında təsvir edilir və sistem Siri və Shortcuts ilə inteqrasiya üçün lazım olan hər şeyi avtomatik yaradır.

WWDC 2024 "Dive deeper into App Intents" sessiyasına görə, Apple AppIntent-i tətbiqlərin funksionallığını ənənəvi UI-dən kənarda genişləndirmək üçün mərkəzi mexanizm kimi görür. iOS 18 buraxılana qədər App Store-un top 100 tətbiqinin 70%-dən çoxu artıq AppIntent-dən Shortcuts və Siri ilə inteqrasiya üçün istifadə edir və orta iOS 18 istifadəçisi səs əmrləri və ya vidjetlər vasitəsilə gündə 4–6 intent işlədir.

AppIntent harada istifadə olunur

• Siri — səs əmrləri: “Hey Siri, MyApp-ə tapşırıq əlavə et”
• Shortcuts — parametrlərin konfiqurasiyası ilə Qısayollar tətbiqində avtomatlaşdırma
• Spotlight — axtarış zolağından birbaşa əmrlərin axtarılması və yerinə yetirilməsi
• Control Center — iOS 18+ üçün sürətli hərəkət düymələri
• Action Button — iPhone 15 Pro və daha yeni modellərdə düymə üçün hərəkətin konfiqurasiyası

AppIntent vs Intents framework: əsas fərqlər

Intents framework (iOS 10–15) .intentdefinition faylının yaradılmasını, Xcode vasitəsilə ObjC/Swift siniflərinin generasiyasını, Intents Extension və App Intent Configuration konfiqurasiyasını tələb edirdi. AppIntent (iOS 16+) bu kəməri generasiya, genişlənmələr və əlavə konfiqurasiyalar olmadan təmiz Swift kodu ilə tamamilə əvəz edir. Bu, intentlərin yaradılması prosesini SiriKit öyrənmədən adi iOS tərtibatçısı üçün əlçatan edir.

AppIntent-in əsas üstünlüyü deklarativlikdir. Tərtibatçı intentin nə etdiyini təsvir edir, sistemlə necə inteqrasiya olunduğunu yox. Çərçivə Siri dialoq ssenarilərini, Shortcuts-da parametrlərin göstərilməsini və intentlər arasında kontekstin ötürülməsini özü idarə edir. Köhnə Intents framework-da inteqrasiyanın hər aspekti əl ilə kodlaşdırılmalı idi, o cümlədən intent UI-nı göstərmək üçün INUIHostedView.

Yanaşmaların müqayisəsi

Əsas protokollar: AppIntent, AppEntity, AppEnum

AppIntent — intenti təyin edən mərkəzi protokol. O, title (Siri üçün ad), description (Shortcuts-da təsvir), parametrlər (@Parameter vasitəsilə) və IntentResult qaytaran perform() metodunu ehtiva edir. Nəticə IntentDialog (Siri ilə dialoq), Shortcuts-a qaytarılacaq dəyər və ya xəta ola bilər. Hər intent həmçinin suggestedInvocationPhrase — səs çağırışı üçün ifadə təmin edə bilər.

AppEntity intentlərin işlədiyi varlıqları təsvir edir. Məsələn, tətbiq layihələri idarə edirsə, AppEntity Project id, displayRepresentation (varlığın UI-da necə göstərilməsi) və defaultQuery (varlıqların necə axtarılması) ehtiva edir. AppEnum — Shortcuts-da picker elementi ilə UI yaradan seçim parametrləri üçün sadalama. Parametrlər siyahısını əl ilə yaratmaq əvəzinə, AppEnum-a uyğun enum elan etmək kifayətdir.

AppEnum və parametr nümunəsi

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 parametrləri və onların validasiyası

AppIntent parametrləri @Parameter property wrapper vasitəsilə elan edilir, bu da avtomatik olaraq Shortcuts UI və Siri səs sorğuları ilə inteqrasiya olunur. Hər parametrin title (Shortcuts-da göstərilir) var və təsvir, standart dəyərlər, məhdudiyyətlər ehtiva edə bilər. AppIntent standart tipləri dəstəkləyir: String, Int, Double, Bool, həmçinin AppEntity və AppEnum vasitəsilə fərdi tiplər.

Parametrlərin validasiyası məntiqin yerinə yetirilməsindən əvvəl perform() metodunda həyata keçirilir. Parametrlər düzgün deyilsə, intent IntentError vasitəsilə xəta qaytarır. Mürəkkəb validasiya üçün perform()-dan əvvəl çağırılan və əmrin yerinə yetirilməsindən əvvəl IntentDialog vasitəsilə istifadəçiyə əks əlaqə təmin edə bilən validate() metodu tətbiq oluna bilər. Bu, xüsusilə Siri səs ssenarilərində faydalıdır, burada istifadəçini yenidən soruşmaq səhv əmri yerinə yetirməkdən asandır.

Validasiya ilə parametrlər

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-də intentin yaradılması: nümunə

Tətbiqdə qeydlərin axtarılması üçün intentin tam nümunəsi AppEntity və EntityQuery ilə işi nümayiş etdirir. SearchNotesIntent intenti axtarış sətri qəbul edir və tapılan qeydlərin siyahısını qaytarır. AppEntity Note qeydin strukturunu təsvir edir, EntityQuery isə anbarda axtarışı həyata keçirir. Nəticə Shortcuts-un istifadəçiyə göstərdiyi varlıqlar massivi ilə IntentResult vasitəsilə qaytarı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 və Siri ilə inteqrasiya

AppIntent elan edildikdən sonra Shortcuts və Siri ilə inteqrasiya avtomatik baş verir. Shortcuts tətbiqi qurulmuş tətbiqlərdən bütün AppIntent-ləri skan edir və onları mövcud əməliyyatlar siyahısında göstərir. İstifadəçi əmrinə intent əlavə edə, parametrlərini konfiqurasiya edə və digər əməliyyatlarla birləşdirə bilər. Siri üçün intentlər tərtibatçı tərəfindən əlavə konfiqurasiya olmadan səs əmrləri kimi görünür.

Tərtibatçı suggestedInvocationPhrase — səs çağırışı üçün tövsiyə olunan ifadə əlavə etməklə inteqrasiyanı yaxşılaşdıra bilər. Məsələn, tapşırıq əlavə etmə intenti üçün: suggestedInvocationPhrase = "Add new task". Siri bu ifadəni təhlil edir və səs əmrlərinin öyrədilməsi zamanı istifadəçiyə təklif edir. Həmçinin categories — intentin kateqoriyasını (create, view, search, edit) təyin etmək olar, bu da Shortcuts-a əməliyyatları mənaya görə qruplaşdırmağa kömək edir.

Shortcuts üçün intent kateqoriyaları