Shortcuts let you expose the capabilities of your apps to Siri
- Siri suggestions will show siri shortcuts
- Siri can suggest shortcuts on the watch
- Shortcuts can be shown on the lock screen
- Users can provide their own commands for shortcuts and developers can define their own responses
- Developers suggest commands that the users can use
- Shortcuts even work on HomePod
- Shortcuts from your app show up in the Shortcuts App
- Define a shortcut, come up with an idea
- Donate shortcut to Siri
- Handle the user action
A great shortcut should:
- Accelerate an action that the user performs
- Be of persistent interest to the user
- Be executable at any time
The more a user uses your shortcuts, the more Siri will suggest your shortcuts.
Two ways to provide / donate a shortcut:
- NSUserActivity
- Intents
Developers can now define their own, custom, intents.
NSUserActivity is a good option for something that is opened in your app, or if your offering content that you also index in Spotlight for instance.
Intents provide the richest experience and are used for more complex interactions.
Set isEligibleForPrediction = true to make a user activity available for Siri suggestions. You should assign userInfo and provide suggestedInvocationPhrase. Lastly, you should make the activity the current activity.
To handle user activity, implement the handler that is already available in app delegate.
You start by thinking about the type of intent you need. For instance an existing one like messaging, workouts, lists, payments etc. To make a custom one, create a new intent definition file and configure it using the intent editor.
Your intent has some metadata that categorizes your intent. There are a lot of categories available, like order or even do. You also provide a title and description and define whether the user must confirm the action themselves.
You must also provide some parameters you give it a name, a type and specify if it should be an array. You must also add shortcut types. A shortcut type has a combination of available paramaters and format to show a title and description for the shortcut. Your shortcut can optionally be executed in the background if you don’t need to open your app.
Shortcut types that can be executed in the background are often better. You can set up up to 16 shortcut types for an intent.
Some intent handling code is provided by Xcode. You should make sure that the intent definition is included in all relevant targets.
An intent is donated as an INInteraction. Make sure to donate the intent every time the user perform an action that is equivalent to invoking your shortcut. This teaches Siri when to suggest your intent.
Handle intents in continue user activity in app delegate for foreground shortcuts. The best experience is through an extension.
Use the intent extension for the best experience. Conform to your intent handling protocol and implement confirm and handle. If you can’t confirm the intent, then return an error code. Handling means you execute the action. Make sure to implement intent extensions for every shortcut that your user can use in the background. This also enables you to add siri shortcuts to the apple watch. INRelevantShortcut helps with showing your shortcut on the apple watch.
You can also set requiredUserInfoKeys, no idea what it is. Something to look in to.
To debug, enable the following in developer settings on the iPhone:
- Display donations on lock screen
- Show suggestions in search
An intent definition file contains many intents. The definitions file should be added to the targets in which you want to use it. Select “No generated classes” for targets where you do want your intents, but don’t want generated code.
Parameters contain the data that is present in your app. You can use the parameters in your intent’s shortcut title.
Any suggestion you donate is added to the settings app and the user can quickly record their own commands to use them with their voice.
It’s very important to donate the suggestion at any time the user does whatever your shortcut would do.
When you donate a suggestion, Siri will look at time, location and other metadata to make the best suggestion at the best times.
The requiredUserInfoKeys specify what metadata from the userInfo dict should be used by siri to look for patterns. Imagine you have scroll position in your user activity. If siri takes this into account, it will have a hard time if the scroll position is different every time. If scroll position is not present in requiredUserInfoKeys, siri can ignore scroll position during its learning. This only applies to user activities.
Intent parameter types are the more powerful intent version of required keys.
- Something that is likely repeated
- Consistent payload across donations since it is used for pattern finding
- Do not include timestamps. Prefer “Today” over a certain fixed date.
- Donate once, and only once for each user action
You can use enums when the values for a parameters are clearly bounded. Example is sizes for soup or coffee ( S / M / L )
If you donate shortcuts that link to deletable content. Make sure to delete the shortcut when the user deletes the content.
If you use user activities, the unique identifier is used to delete. For instance, delete from spotlight will also delete the shortcut.
persistentIdentifier is new and can be used to delete activities from siri.
An intent can be deleted using identifier and groupIdentifier on INInteractiion. deleteAll deletes all intents.
INPlayMediaIntent is used to play media. You can use this in the background. These shortcuts are shown on the play controls on the home screen in addition to all the other places. Play media shortcut works great with HomePod.
INUpcomingMedia can be used to tell the system about content the user hasn’t seen yet. Like podcasts or tv shows.