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.

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.

Your app can make donations using an NSUserActivity object or INInteraction object. Both ways of donating are described in the sections that follow.

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

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 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 intent parameter object for the custom type.