Tell Siri about shortcuts to actions that the user performed in your app.
Siri can predict shortcuts to actions that a user may want to perform using your app, and suggest those shortcuts to the user in places such as Spotlight search, Lock Screen, and Siri Watch Face. Siri learns about the shortcuts available for your app through donations that your app makes to Siri. Users can also use donated shortcuts to add personalized voice phrases to Siri. To learn more about adding phrases to Siri, see Shortcut Management.
When to Donate
You should donate a shortcut each time the user performs the action in your app. For example, if the user can order soup from a restaurant using your app, donate a shortcut for the order soup action after the user places their order. Don’t make donations for actions that the user has not completed in your app; if the user never places an order for soup, you should never donate a shortcut for the order soup action.
Donate a User Activity
NSUser provides a lightweight approach for making a donation that also integrates with other Apple features such as Handoff and Spotlight search.
To make a donation using
NSUser, define the activity as a type in the
NSUser array in your Info.plist. The activity type should be a reverse domain name that is unique within the list.
In your app, create an instance of
NSUser and set its
required with information that your app needs to resume the activity at a later time. Also set the
is property to
true and the
persistent to a unqiue string value, which is needed to delete the donation (see Deleting Donated Shortcuts). You can also suggest the voice phrase that a user may want to use when adding a phrase to Siri by setting the
suggested property on the user activity.
Next, call the
become method on the user activity object to mark it as current, which donates the activity to Siri. Alternatively, you can attach the object to a
UIResponder object, which also marks the activity as current.
To handle the action at a later time, implement the
application(_: method in your app delegate.
Donate an Interaction
The other way to make a donation is to use an
INInteraction object. This involves a bit more work, but gives you more control over defining and handling the action.
Before diving into the source code, look through the list of system-provided intents to see if one exists that’s suitable for your action (see Intent Domains). Use an intent that best describes the action; otherwise, create a custom intent.
To donate the intent, create an instance of the intent class. Set its parameter values and add images to the parameters as needed. To recommend a voice phrase that the user may want to add to Siri, set the intent’s
suggested property to a string containing the phrase.
To handle the shortcut, implement the
application(_: method in your app delegate. When the time comes to handle the action, the system opens your app. To provide a better user experience—one where opening your app each time to handle the shortcut isn't necessary—provide an Intents App Extension with your app. The extension handles the shortcut in the background without needing to open your app, providing a richer experience that occurs within Siri. For more information on Intents App Extensions, see Creating an Intents App Extension.
Even if you provide an Intents App Extension, you should always implement the
application(_: method in your app delegate. Certain user activities—such as tapping a shortcut in Siri—open your app, and the user expects the app to handle that shortcut. Your app is also responsible for handling shortcuts that cannot be run in the background; for example, when your apps needs to ask the user for additional information before completing the action.