Article

Donating Shortcuts

Tell Siri about shortcuts to actions that the user performed in your app.

Overview

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:

  • NSUserActivity. 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

NSUserActivity 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 NSUserActivity, define the activity as a type in the NSUserActivityTypes 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 NSUserActivity and set its title, userInfo, and requiredUserInfoKeys with information that your app needs to resume the activity at a later time. Also set the isEligibleForPrediction property to true and the persistentIdentifier 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 suggestedInvocationPhrase property on the user activity.

Next, call the becomeCurrent() 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 UIViewController or UIResponder object, which also marks the activity as current.

To handle the action at a later time, implement the application(_:continue:restorationHandler:) 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 suggestedInvocationPhrase property to a string containing the phrase.

After creating the intent, create an instance of INInteraction and call its donate(completion:) method, passing in the intent. This tells Siri about the shortcut.

To handle the shortcut, implement the application(_:continue:restorationHandler:) 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(_:continue:restorationHandler:) 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.

See Also

Shortcuts

Deleting Donated Shortcuts

Remove your donations from Siri.

Soup Chef: Accelerating App Interactions with Shortcuts

Make it easy for people to use Siri with your app by providing shortcuts to your app’s actions.

Shortcut Management

Enable users to add shortcuts to Siri, and have your app suggest shortcuts to users.

Relevant Shortcuts

Display shortcuts on the Siri watch face.

Media Intent Shortcuts

Provide a convenient way for users to listen to and watch media content from your app with shortcuts.

enum INShortcut

An action available in your app that the system may suggest to a user or a user may add to Siri.

class INInteraction

An interaction between the user and your app involving an intent object.

class INObject

An object that represents a custom intent parameter.