App Intents for Capacitor Apps

Add native App Intents to the iOS project so system surfaces can run app actions, and connect them to the web layer. App Intents are Swift only. There is no JavaScript API for them, so every intent is native code in the App target or an extension, and the web layer is reached through a URL or a small local plugin.

When to Use

TRIGGER when:

• The user wants Siri phrases, Shortcuts actions, App Shortcuts, Spotlight actions, Action button or Apple Intelligence integration for a Capacitor app
• The user wants a widget button or a Control Center control to run an app action
• An intent opens the app, but the web view does not navigate, or it navigates only on warm launch
• A background intent crashes, times out, or tries to call JS
• Migrating openAppWhenRun to supportedModes, or adopting iOS 26/27 App Intents APIs
• A plugin author wants to ship App Intents with a plugin

Do not use:

• Universal Links / custom scheme / appUrlOpen setup: capacitor-deep-linking
• AppDelegate to SceneDelegate migration: capacitor-uiscene-migration
• Push notification actions: capacitor-push-notifications
• Live Activities or SVG widgets driven from JS: capacitor-plugins (@capgo/capacitor-widget-kit)
• Android app shortcuts and intents: not covered here

Facts that drive the design

• App Intents need iOS 16. Capacitor 8 deploys to iOS 15, so every intent type, entity, query and AppShortcutsProvider needs @available(iOS 16.0, *), or the user raises the deployment target. Capacitor 9 deploys to iOS 16, so the base API needs no gating. Newer APIs still do (tables in references/ios-26-27-apis.md).
• A background intent has no WebView. iOS can launch the app process headless for .background intents. AppDelegate.application(_:didFinishLaunchingWithOptions:) runs, but no scene connects and CAPBridgeViewController never loads. Background intents must do native work only (network, storage, HealthKit, etc.). They cannot call JS or plugins through the bridge.
• perform() is not on the main actor, and it can run more than once. Hop explicitly (await MainActor.run or @MainActor func perform()) before you touch UIKit, the bridge or @MainActor state. Do irreversible work last. Details: references/intent-traps.md.
• With UIScene (Capacitor 8.5+) URL delivery moved. Universal Links and custom-scheme opens reach SceneDelegate and are forwarded by SceneDelegateProxy, which posts the notifications @capacitor/app listens to. If the app still has custom URL code in AppDelegate, it no longer runs. Check capacitor-deep-linking first if appUrlOpen does not fire for a normal link. An intent cannot fix a broken link pipeline.
• On cold launch the JS listener does not exist yet. Any route an intent hands to the web layer must survive until JS asks for it: use App.getLaunchUrl() for URLs, or a pending-route store plus notifyListeners(..., retainUntilConsumed: true) for the local-plugin path.
• Identifiers are a public contract. Intent type names, AppEntity.id values, AppEnum raw values, URL formats and shipped phrases are stored in users' saved shortcuts. Add new ones; do not rename or remove shipped ones without telling the user.

References

Only load a reference when its topic is in play.

Workflow

1. Inspect (read-only)

1. Read package.json (@capacitor/ios version), ios/App/App/Info.plist (scene manifest present?), ios/App/App/AppDelegate.swift, ios/App/App/SceneDelegate.swift, the App target's deployment target, and any existing *.entitlements (Associated Domains, App Groups).
2. Check whether the app already handles deep links in JS (App.addListener('appUrlOpen', ...), App.getLaunchUrl()) and which routes exist.
3. Search for existing intents: grep -rn "AppIntent\|AppShortcutsProvider\|openAppWhenRun" ios/App.
4. List extension targets (widgets) in ios/App/App.xcodeproj/project.pbxproj (PBXNativeTarget entries other than App).

2. Design with the user

For each action the user wants, decide and confirm:

Keep one intent per atomic task. Report the plan (files to add, targets, entitlements, JS changes) before editing.

3. Implement

1. Create the Swift files in ios/App/App/Intents/ with the App target membership (references/project-setup.md).
2. Write the intents following references/intent-traps.md. Gate APIs by version.
3. Add the web bridge (references/web-bridge.md): either reuse the deep-link router, or add the local plugin and register it in a CAPBridgeViewController subclass.
4. Add an AppShortcutsProvider with shortTitle, systemImageName and \(.applicationName) in every phrase.
5. Add entitlements only when needed (App Groups for shared data, Associated Domains for Universal Links), and on every target that uses them.
6. JS side: handle the route on warm and cold start.

4. Verify

npx cap sync ios
xcodebuild -project ios/App/App.xcodeproj -scheme App \
  -destination 'generic/platform=iOS Simulator' build
# CocoaPods projects: -workspace ios/App/App.xcworkspace

• The build log shows the App Intents metadata extraction step with no warnings about phrases. A phrase without \(.applicationName) produces a build warning and is dropped at runtime.
• Product > App Shortcuts Preview in Xcode shows the phrases matching.
• Run on a simulator or device: open the Shortcuts app, find the app's actions, run each one.
  • Background intent: completes without the app coming to the foreground. Check the native logs (ios-android-logs).
  • Foreground intent, app killed first (cold) and app running (warm): the web view lands on the right route both times.
• Spotlight: search the shortcut title.
• If tests exist, add AppIntentsTesting coverage for iOS 27 test runners (references/ios-26-27-apis.md).

Error Handling

Related Skills

• capacitor-deep-linking: Universal Links and appUrlOpen routing the intents rely on
• capacitor-uiscene-migration: required before Xcode 27; moves URL handling to SceneDelegate
• capacitor-plugins: @capgo/capacitor-widget-kit for Live Activities and JS-driven widgets
• capacitor-testing: native unit tests and the device verification loop
• ios-android-logs: logs from headless intent runs