Реализация интеграции с 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 недель. Стоимость зависит от количества и сложности действий.