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 the 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.
Donate Shortcuts at the Right Time
Donate a shortcut each time the user performs the action in your app. Make one, and only one, donation per action at the time the user performs the action. If the user performs the same action again, make another donation. 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. If the user places another order, then make another order soup donation.
However, don't make more than one shortcut donation for an action at the time the user performs the action. Additionally, don’t make donations for actions the user has not completed in your app; if the user never places an order for soup, don't donate a shortcut for the order soup action.
Your app can make donations using one of the following objects:
NSUser. Donate the shortcut using a user activity when the action involves a view within your app, such as displaying recent transactions in a banking app.
INInteraction. Donate the shortcut using an interaction when the action involves a task the user accomplishes with your app, such as recording activity in a ski and snowboard tracking app.
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
eligible property to
YES and the
persistent to a unique 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
You can also make a donation using an
INInteraction object. For this type of donation, you provide the interaction with an intent that represents the action (or task) that the user wants to accomplish using your app. This type of donation has an advantage over ones made with a user activity in that Siri can deconstruct the donation into its intent parameters allowing for more intelligent predictions.
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.