1487 Shortcuts 48e1440a

Shortcuts Integration

AppShortcutsProvider

Registers intents for automatic discovery in Shortcuts app and Siri:

struct LibraryAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OpenCurrentlyReading(),
            phrases: [
                "Open Currently Reading in \(.applicationName)",
                "Show my reading list in \(.applicationName)"
            ],
            shortTitle: "Open Reading List",
            systemImageName: "books.vertical.fill"
        )
    }
}

Phrase Requirements

Critical: Every phrase MUST include .applicationName:

// BAD: Missing app name
phrases: ["Open my books", "Show reading list"]  // Won't be discoverable

// GOOD: Includes app name
phrases: [
    "Open my books in \(.applicationName)",
    "Show reading list with \(.applicationName)"
]

Limits:

• Maximum 1,000 total phrases per app (including parameter variations)
• Use natural language that reads well when spoken

Localization

Phrases must be in AppShortcuts.strings (or AppShortcuts.xcstrings for iOS 18+):

// AppShortcuts.strings
"Open Currently Reading in ${applicationName}" = "Open Currently Reading in ${applicationName}";

Critical: Using Localizable.strings for phrases does NOT work.

Parameterized Phrases

Include parameters using \(.$parameterName):

AppShortcut(
    intent: OpenBook(),
    phrases: [
        "Open \(\.$book) in \(.applicationName)",
        "Read \(\.$book) with \(.applicationName)"
    ],
    shortTitle: "Open Book",
    systemImageName: "book"
)

Warning: Custom AppEntity parameters in phrases may prevent shortcuts from appearing. Test thoroughly.

iOS 17+ Extensions

Define AppShortcutsProvider in App Intents extensions (not main app) for faster startup:

// In App Intents Extension target
struct BookShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] { ... }
}

Extensions skip UI, analytics, and non-critical initialization.

Discovery Issues

Common reasons shortcuts don't appear:

Migration from SiriKit

When migrating from INIntent to AppIntent:

struct OpenBookIntent: AppIntent {
    // Conform for migration
    static var intentClassName: String? = "OpenBookIntent"
}

Warning: CustomIntentMigratedAppIntent conformance breaks iOS 16 even with availability annotations.

Multilingual Considerations

• App names in different languages than Siri's language cause recognition failures
• Test with Siri language matching app language settings
• Consider region-specific phrase variations

Critical Anti-Patterns

// BAD: Phrase without app name
AppShortcut(
    intent: OpenBook(),
    phrases: ["Open my book"],  // Not discoverable by Siri
    ...
)

// GOOD: App name included
AppShortcut(
    intent: OpenBook(),
    phrases: ["Open my book in \(.applicationName)"],
    ...
)

// BAD: Localization in wrong file
// Localizable.strings - WRONG FILE
"Open book" = "Open book";

// GOOD: Use AppShortcuts.strings
// AppShortcuts.strings - CORRECT FILE
"Open book in ${applicationName}" = "Open book in ${applicationName}";

// BAD: Complex entity parameter in phrase (may fail)
AppShortcut(
    intent: ProcessBook(),
    phrases: ["Process \(\.$complexEntity) in \(.applicationName)"],
    ...
)

// GOOD: Simple parameters or none
AppShortcut(
    intent: ProcessBook(),
    phrases: ["Process current book in \(.applicationName)"],
    ...
)

Review Questions

1. Do all phrases include .applicationName? Required for Siri discovery.
2. Are phrases in AppShortcuts.strings? Localizable.strings doesn't work.
3. Is the app bundle correct? Swift Package intents won't appear (pre-iOS 17).
4. Are custom entity parameters tested in phrases? Complex entities may break discovery.
5. Is migration handled carefully? CustomIntentMigratedAppIntent breaks iOS 16.