An interface you use to express app-specific actions and make them available to
the rest of the system.
The ``AppIntent`` protocol defines the interface you use to make your app’s actions
discoverable by Apple Intelligence and Siri, the Shortcuts app, and other system experiences. This protocol
defines the common features that help the system identify your app’s actions and access
basic information about them. Implement this protocol in all your app intents, and
supplement it with other protocols as needed to support specific types of actions.
Implement this protocol in a new type or existing type in your app, app extension, framework,
or Swift package. In your type, use the ``AppIntent/perform()`` method to perform the action
and return a result back to the system. If you require input from the person performing
the action, add one or more variables to your type and apply the `@Parameter` property wrapper
to each. For example, an app intent to start a workout might require the person to specify
which workout they want. Before calling your ``AppIntent/perform()`` method, the system
resolves any parameters with this wrapper by inferring values from the current conversation
or by asking someone explicitly to provide the value. If your app intent requires
app-specific data to perform its action, apply the `@Dependency` property wrapper
to any variables with that data.
In addition to performing an action, an app intent provides information about the action
itself. Implement the ``AppIntent/title`` and ``AppIntent/description`` properties and set
them to localized strings describing your action. If your app intent has parameters, fill
in the ``AppIntent/parameterSummary`` property with a description of the action and
parameters together. The system uses this information during conversations or when
displaying information about your intent.
The following example shows an app intent for ordering an album of music. The intent
requires the person to specify the album name at order time. The intent also uses an
internal album manager type to locate albums by name and initiate the purchase.
```swift
struct OrderAlbum: AppIntent {
static var title: LocalizedStringResource { "Order Album" }
static var description = IntentDescription("Order a vinyl record album.")
@Parameter(title: "Album", description: "The name of the album to order.")
var albumName: String
@Dependency
private var albumManager: AlbumDataManager
func perform() async throws -> some IntentResult {
// Perform the action...
return .result()
}
static var parameterSummary: some ParameterSummary {
Summary("Order \(\.$albumName)")
}
}
```
In addition to this protocol, you can define intents that support common actions. System-defined
schemas define the requirements needed to support common actions, including the app
intent protocol your type needs to adopt and any parameters it needs to define. For example, the
``AssistantSchemas.PhotosIntent.openAlbum`` intent requires conformance to the
``OpenIntent`` protocol and a property with an ``AppEntity`` type for the photo album.
For information about the available schemas, see <doc:app-schema-domains>.
For additional app intent protocols you can adopt in your app, see <doc:app-intent-types>.
For information on how to create an app intent, see <doc:Creating-your-first-app-intent>.
Pauses the app intent and asks the person to choose an option from the specified list.
- Parameters:
- options: The options to choose from. The prompt displays the options in the same
order as they appear in the array, with one exception. If the list includes the
``IntentChoiceOption/cancel`` option, the system places that option according
to the platform’s conventions.
- dialog: The localized text you want the system to display or speak. Provide instructional text
or a question to help the person choose an option.
- Returns: The option the person chose.
- Throws: An error if the person chooses a cancel option from the interface.
Call this method from the ``AppIntent/perform()`` method of your app intent when
you need someone to confirm an action, disambiguate from a set of possibilities, or select
an intent-specific behavior before proceeding. The system displays a standard interface with
the provided set of options and asks the person to choose one. When someone makes a selection,
the method returns the option and your app intent continues to run. This method throws an error
if someone cancels the request using a cancel button, a ``IntentChoiceOption/cancel`` option,
or a system-provided gesture.
get · iOS 16.0+
systemContext
Swift declaration
var systemContext: IntentSystemContext { get }
Contextual information that the system provides while it performs the app intent.
Access information the system provides to your app intent while it performs its action in its ``AppIntent/perform()`` implementation.
The available information varies by platform. For example, in watchOS, the intent system context
includes a precise timestamp
when a person starts the app intent's action using the Action button on Apple Watch Ultra.
Displays a confirmation prompt that includes an interactive snippet.
- Parameters:
- conditions: The conditions to check before asking for confirmation.
- actionName: The action associated with the request. The system puts the action name
in the button that confirms the action.
- dialog: The localized text you want the confirmation request to display or speak.
- showDialogAsPrompt: `true` to include the contents of the `dialog` parameter in
the confirmation interface. Specify `false` to omit the dialog from the interface.
- snippetIntent: The snippet to display in the confirmation interface.
Call this method when you want someone to confirm a particular choice. For example, call this
method before someone performs an action that might be destructive or unsafe. The
method displays a confirmation interface that includes the provided snippet and optional dialog text.
The interface asks the person to confirm or cancel the operation, and returns normally
if the person confirms the operation. If the person chooses the cancel option, the method
throws an error.
The code that shows your snippet can potentially modify parameter values in your app intent
type. After this function returns, retrieve the latest values from properties instead of
relying on cached versions of that data.
Displays a confirmation prompt that includes the specified text and action details.
- Parameters:
- conditions: The conditions to check before asking for confirmation.
- actionName: The action associated with the request. The system puts the action name
in the button that confirms the action.
- dialog: The localized text you want the confirmation request to display or speak.
Call this method when you want someone to confirm a particular choice. For example, call this
method before someone performs an action that might be destructive or unsafe. The
method displays a prompt that includes the provided information and asks the person to confirm or
cancel the operation. The method returns normally if they confirm the operation, but
throws an error if they cancel it.
method · iOS 16.0+
requestConfirmation
Swift declaration
func requestConfirmation() async throws
Displays a prompt that asks the person for confirmation before performing the app intent.
Call this method before performing any work that might be destructive or unsafe. The
method displays a prompt that asks the person to confirm or cancel the operation. The
method returns normally if they confirm the operation, but throws an error if they cancel it.
Attempts to transition the app to the foreground after optionally requesting permission to do so.
- Parameters:
- dialog: The localized text you want the system to display or speak to confirm the transition.
- alwaysConfirm: `true` to ask the person to confirm the transition.
If you specify `false`, the system might not ask for confirmation if it already received
a recent confirmation. It doesn't ask for confirmation if you recently called a `requestChoice`
or `requestConfirmation` method of your intent, or asked to disambiguate a value. It does
ask for confirmation if your app intent conforms to the ``ProgressReportingIntent``
protocol but didn't update the progress value recently.
Call this method from your app intent’s ``AppIntent/perform()`` method when you want to continue
running your code in the foreground. Before calling this method, use the contextual information
in the intent’s ``AppIntent/systemContext`` property to verify the app can transition to the
foreground. If you call this method and it’s not possible to transition the app to the foreground,
the system throws an ``AppIntentError/Unrecoverable/notAllowed`` error.
Asks the person to continue the intent’s action in the foreground.
- Parameters:
- dialog: The localized text you want the system to display or speak to confirm the transition.
- alwaysConfirm: `true` to ask the person to confirm the transition.
If you specify `false`, the system might not ask for confirmation if it already received
a recent confirmation. It doesn't ask for confirmation if you recently called a `requestChoice`
or `requestConfirmation` method of your intent, or asked to disambiguate a value. It does
ask for confirmation if your app intent conforms to the ``ProgressReportingIntent``
protocol and you didn't update the progress value recently.
If your intent code encounters an error and needs to continue in the foreground, call this
method to start the transition process. Before calling this method, use the contextual
information in the intent’s ``AppIntent/systemContext`` property to verify the app can
transition to the foreground. If you call this method and it’s not possible to transition
the app to the foreground, the system throws an ``AppIntentError/Unrecoverable/notAllowed`` error.
Donates the app intent to the system.
When someone interacts with your app’s interface, create an app intent for
the interaction and call this method. Donating intents helps the system predict
future actions and improve the overall system experience. Don’t donate app intents
that the system creates and asks you to handle.
Call this method to donate the intent synchronously, which you might do if you’re
not using Swift concurrency. The system ignores any exceptions it encounters
during the donation process.
- Returns: An opaque identifier you can use to manage the donation later using
an ``IntentDonationManager`` type.
Donates the app intent to the system asynchronously.
When someone interacts with your app’s interface, create an app intent for
the interaction and call this method. Donating intents helps the system predict
future actions and improve the overall system experience. Don’t donate app intents
that the system creates and asks you to handle.
- Returns: An opaque identifier you can use to manage the donation later using
an ``IntentDonationManager`` type.
Skipped declarations
15 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
AppIntent.openAppWhenRun
Static protocol requirements cannot be called through an instance.
AppIntent.authenticationPolicy
Static protocol requirements cannot be called through an instance.
AppIntent.description
Static protocol requirements cannot be called through an instance.
AppIntent.persistentIdentifier
Static protocol requirements cannot be called through an instance.
AppIntent.parameterSummary
This protocol needs associated types that cannot yet cross the bridge.
AppIntent.isDiscoverable
Static protocol requirements cannot be called through an instance.
AppIntent.allowedExecutionTargets
Static protocol requirements cannot be called through an instance.
AppIntent.donate(result:)
This protocol needs associated types that cannot yet cross the bridge.
AppIntent.donate(result:)
This protocol needs associated types that cannot yet cross the bridge.
AppIntent.callAsFunction(donate:)
The iOS SDK compiler rejected this binding: no exact matches in call to instance method 'callAsFunction'
AppIntent.callAsFunction(donate:)
The iOS SDK compiler rejected this binding: no exact matches in call to instance method 'callAsFunction'
The iOS SDK compiler rejected this binding: instance method 'requestConfirmation(conditions:actionName:dialog:showDialogAsPrompt:snippetIntent:)' requires that 'EmptySnippetIntent.PerformResult' (aka 'some ShowsSnippetView') conform to 'ReturnsValue'
