Expose app actions and entities to Siri, Shortcuts, Spotlight search, interactive widgets, Control Center, and Apple Intelligence using the AppIntents framework. Targets Swift 6.3 / iOS 26+.
Contents
- Triage Workflow
- System Surface Integration Matrix
- AppEntity and EntityQuery
- AppShortcuts and Voice Phrases
- Route by Task
- Common Mistakes
- Review Checklist
- References
Triage Workflow
- Select core actions: Expose 1–3 high-value user tasks that make sense outside the app.
- Define AppEntity models: Create identifiable shadow models (
AppEntity) for domain data referenced by the intent. - Implement AppIntent: Define parameters with
@Parameter, implementperform() async throws -> some IntentResult. - Register voice phrases: Provide natural voice invocations with
AppShortcutsProvider. - Verify system surface: Test discovery in Shortcuts, Spotlight search, and widget configuration.
System Surface Integration Matrix
| System Surface | Protocol / Attribute | Purpose |
|---|---|---|
| Siri & Shortcuts | AppIntent |
Direct voice and shortcut automation |
| Configurable Widgets | WidgetConfigurationIntent |
Supplies parameters to widget timelines |
| Control Center | ControlConfigurationIntent |
Powers Control Center buttons and toggles |
| Spotlight Search | IndexedEntity |
Indexes domain items into on-device Spotlight |
| Apple Intelligence | @AppIntent(schema:) |
Assistant semantic reasoning and tooling |
| Interactive Snippets | SnippetIntent |
In-line system confirmation views (iOS 26+) |
AppEntity and EntityQuery
Expose domain data to intents using AppEntity:
struct OrderEntity: AppEntity {
static var defaultQuery = OrderQuery()
static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Order")
var id: UUID
var displayRepresentation: DisplayRepresentation {
DisplayRepresentation(title: "\(orderNumber)")
}
}
Implement EntityQuery to resolve identifiers (entities(for:)) and provide suggested choices (suggestedEntities()).
AppShortcuts and Voice Phrases
Expose voice triggers without requiring user setup via AppShortcutsProvider:
- Register app shortcut phrases using
\(.applicationName)token. - Provide clean fallback phrases for Siri matching.
Route by Task
- For
@Parametertypes,AppEntitydeclarations, andEntityQueryvariants, read Parameters and Entity Queries. - For widget controls, interactive snippets, and Lock Screen integrations, read System Surfaces.
- For Siri voice matching, confirmation dialogs, and authentication policies, read Assistant Focus and Intent Behavior.
- For Spotlight search indexing, deep link routing, and
IndexedEntity, read URL and Spotlight Integration.
Common Mistakes
- Performing UI navigation or view presentation directly inside
perform()without returning anOpenURLIntentor navigation result. - Forgetting to provide an
EntityQueryfor custom@Parameterentity types, breaking Shortcuts parameter selection. - Hardcoding the app name in
AppShortcutphrases instead of using\(.applicationName). - Running long network calls in
perform()without checkingTask.isCancelledor providing progress dialogs. - Omitting
typeDisplayRepresentationonAppEntityconformances.
Review Checklist
- Intent conforms to
AppIntentor specialized surface protocol - Parameters have clear titles and valid default/suggested values
- Entities implement
EntityQuerywithentities(for:)andsuggestedEntities() -
perform()returns an appropriateIntentResult(e.g..result(),.result(dialog:)) - Shortcuts phrases use
\(.applicationName)macro - Destructive actions declare
requestConfirmation()before executing - Sensitive actions require device authentication where appropriate