Реалізація інтеграції з Shortcuts (Apple) у мобільному додатку
Додаток Shortcuts (Швидкі команди) дозволяє користувачам створювати автоматизації з дій різних додатків. Якщо ваш додаток надає App Intents, користувач може включити його в будь-яку автоматизацію: «Коли я приїжджаю домой — відкрити мій плейлист у [вашому додатку] та включити світло». Інтеграція зі Shortcuts — це не просто «підтримка голосових команд», це участь в екосистемі автоматизації Apple.
App Intents — правильний шлях з iOS 16
До iOS 16 інтеграція будувалась на SiriKit з .intentdefinition файлами та INExtension в окремому таргеті. З iOS 16 — AppIntents framework. Менше шаблонного коду, немає кодогенерації, Intent одразу видно в Shortcuts без додаткової настройки.
Мінімальний Intent для Shortcuts:
struct StartWorkoutIntent: AppIntent {
static var title: LocalizedStringResource = "Почати тренування"
static var description = IntentDescription(
"Запускає тренування у додатку",
categoryName: "Тренування"
)
static var openAppWhenRun: Bool = false // не відкривати додаток
@Parameter(title: "Тип тренування")
var workoutType: WorkoutType
func perform() async throws -> some IntentResult & ProvidesDialog {
try await WorkoutService.shared.start(type: workoutType)
return .result(dialog: "Тренування \(workoutType.name) почалось")
}
}
openAppWhenRun: Bool = false — ключове для автоматизацій. Intent виконується у фоні без відкриття додатку. Для Shortcuts це критично — інакше при автоматизації екран вспиха й відкриється ваш UI.
Параметри та динамічні значення
Статичні параметри (String, Int, Bool, Date) — просто властивості з @Parameter. Динамічні — через AppEntity з AppEntityQuery.
enum WorkoutType: String, AppEnum {
case running, cycling, swimming
static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Тип тренування")
static var caseDisplayRepresentations: [WorkoutType: DisplayRepresentation] = [
.running: "Біг",
.cycling: "Велосипед",
.swimming: "Плавання"
]
}
AppEnum — закритий список. AppEntity + AppEntityQuery — динамічний список з бази даних додатку. Якщо користувач додав кастомний тип тренування, він повинен з'явитися в Shortcuts як опція — тільки через AppEntityQuery.entities(matching:).
Результати та передача даних між діями
Shortcuts дозволяє передавати результат однієї дії в іншу. Для цього Intent повинен повернути конкретний тип, а не просто діалог.
func perform() async throws -> some IntentResult & ReturnsValue<WorkoutSummary> {
let summary = try await WorkoutService.shared.getLastSummary()
return .result(value: summary)
}
WorkoutSummary — структура з AppEntity або базовим типом. Тепер наступний блок у Shortcuts може отримати ці дані як параметр.
App Shortcuts: фрази без настройки
AppShortcutsProvider — фрази, які працюють без ручної настройки користувачем:
struct FitnessAppShortcuts: AppShortcutsProvider {
static var appShortcuts: [AppShortcut] {
AppShortcut(
intent: StartWorkoutIntent(),
phrases: [
"Почни тренування в \(.applicationName)",
"Запусти \(.applicationName)"
],
shortTitle: "Почати тренування",
systemImageName: "figure.run"
)
}
static var shortcutTileColor: ShortcutTileColor = .teal
}
Фраза з \(.applicationName) — обов'язкова. Apple перевіряє наявність імені додатку у фразі на ревью. Без нього — rejection.
З iOS 17 можна використовувати параметри прямо у фразах: «Почни біг у (.applicationName)» — Siri розпізнає «біг» як значення параметра workoutType.
Віджети та Shortcuts разом
З iOS 17 кнопки у віджетах використовують той же AppIntent. Один Intent — працює й як дія в Shortcuts, й як кнопка у віджеті, й як голосова команда. Це значно спрощує розробку: логіка написана один раз.
Тестування
У симуляторі: Settings → Siri & Search → [додаток] — показує зареєстровані Intents. Додаток Shortcuts у симуляторі дозволяє додати Intent в automation вручну та виконати.
Для App Shortcuts: XCTest з XCTOSSignpostExpectation або просто запуск через Shortcuts.app та перевірка результату.
Розклад
Базова інтеграція 3–5 Intent без AppEntity: 2–4 тижні. Повна інтеграція з AppEntity, App Shortcuts, передачею значень між діями: 5–9 тижнів. Міграція зі SiriKit Intents на App Intents: 3–6 тижнів. Вартість залежить від кількості та складності дій.