WWDC22: Implement App Shortcuts with App Intents | Apple

WWDC22 — Implement App Shortcuts with App Intents

(Michael Sumner)

What App Shortcuts are

• App Shortcuts let your app expose ready-to-run intent actions system-wide (Shortcuts app, Siri, Spotlight) without any user setup. Intents become available as soon as the app is installed.
• They enable quick, lightweight interactions (for example, “start a meditation session”) and reduce friction compared with the older Add to Siri flow.

Key framework and architecture

• App Intents is a Swift-only framework. Intents are defined in Swift (no separate metadata), which simplifies code review and merges.
• Core types / APIs:
  • AppIntent protocol — implement as a Swift struct; requires a title and an async perform() method that executes logic and returns a result (dialogs, optional SwiftUI view).
  • AppShortcutsProvider — returns AppShortcut instances your app exposes (maximum 10 total per app).
  • AppShortcut — ties an intent instance to an array of spoken trigger phrases (use the .applicationName token to let Siri substitute the app name / synonyms).
  • @Parameter property wrapper — mark intent properties that are parameters.
  • AppEntity protocol — make complex parameter types (entities) usable by App Intents.
  • EntityQuery / EntityQuery.suggestedEntities (or suggestedResults) — lookup/suggestion APIs for entities and to provide suggested parameter values for parameterized phrases.
  • updateAppShortcutParameters() — notify the framework when app-side parameter lists change so App Intents can regenerate parameterized phrases.

Parameters and user prompts

• Use parameters to select specific items (for example, a MeditationSession entity with name + identifier).
• App Intents supports three prompt types when a parameter value is needed:
  • Disambiguation — choose from a fixed list (best for small finite sets).
  • Value prompt — open-ended values like strings or numbers (free-form input).
  • Confirmation — verify a value.
• Use disambiguation for fixed session lists; App Intents will present list items using the entity’s display representation.
• Avoid overusing prompts — they slow interactions. Prefer parameterized phrases when possible.

Parameterized phrases

• Parameterized trigger phrases let users speak the parameter inside the initial utterance (for example, “Start a calming meditation”).
• To support parameterized phrases:
  • Implement suggestedEntities / suggestedResults to return candidate values.
  • Call updateAppShortcutParameters() when your data changes.
  • Add phrases to your AppShortcut that reference the parameter key path; the framework composes phrases with the returned entity values.
• Note: parameterized phrases require your app to have launched and updated the framework at least once. If your app hasn’t launched yet, those phrases won’t appear — consider supplying some non-parameterized phrases for initial discoverability.

Custom UI for intents

• Custom views are SwiftUI-based (the same view tech used for widgets) and can be returned from your intent to display in Siri snippets.
• Constraints:
  • No interactivity or animations (widget-like limitations).
  • Views may be shown at value confirmation, intent confirmation, or after execution.

Discoverability and UX guidance

• Phrase design: keep phrases short, memorable, and varied. Provide alternatives and consider using the app name as a noun or verb when appropriate.
• App name synonyms: configure them to help Siri match user language.
• Siri Tip: a contextual UI element (SwiftUI / UIKit styles available) to promote shortcuts inside your app; it supports dismissal and a custom handler. This replaces the old Add to Siri button.
• ShortcutsLink: a UI element to open the app’s shortcuts list (useful when you expose many shortcuts).
• Ordering matters: shortcuts are displayed in the order you list them in code. The first phrase in the phrase array becomes the primary phrase and tile label — put your best / most-used shortcuts first.
• Handle edge cases: support pre-launch scenarios (for example, require login). Your intent should fail gracefully with a helpful error. Siri also surfaces available App Shortcut phrases automatically for queries like “What can I do here?”

Implementation checklist (high level)

1. Define an AppIntent struct with a title and async perform() (return dialogs, optionally a SwiftUI view).
2. Add parameters as properties, annotated with @Parameter.
3. For complex parameters, define an AppEntity type (id, display representation).
4. Implement an EntityQuery for lookup by id and implement suggestedEntities to supply parameter values.
5. Create an AppShortcutsProvider returning AppShortcut(s) that reference the intent and provide an array of trigger phrases (use .applicationName where helpful).
6. If using parameterized phrases, call updateAppShortcutParameters() when data changes.
7. Add custom SwiftUI snippet views if desired (respect widget-like constraints).
8. Add Siri Tip and/or ShortcutsLink in your app UI to promote discoverability. Include some non-parameterized phrases so shortcuts show before first launch if needed.
9. Localize titles, phrases, and dialog strings.

Design guidance and resources

• Keep prompts and follow-ups minimal to preserve quick interactions.
• Prefer parameterized phrases for fixed/known parameter sets; don’t expect arbitrary open-ended values to work reliably in the initial utterance.
• For deeper design guidance, see the related session “Design App Shortcuts” (Lynn) and the App Intents documentation and other WWDC talks.

Main speaker / sources

• Michael Sumner — Software Engineer on Siri and App Intents (presenter).
• Related session referenced: “Design App Shortcuts” (Lynn).