Select Page


Siri shortcuts are a new feature introduced in iOS 12 that allow the user to trigger an action in your app via a “Hey Siri” phrase. Shortcuts can also be triggered by a tap on a shortcut from the lock screen, search screen, etc.

In this post we create a simple Siri shortcut demo app using an NSUserActivity-based approach. The app allows the user to trigger the Siri shortcut using a “Hey Siri” phrase.

Download the demo app source from GitHub



What are Siri Shortcuts and how do I create them?

Siri shortcuts are a new feature introduced in iOS 12 that allow the user to trigger an action in your app via a “Hey Siri” phrase. Shortcuts can also be triggered by a tap on a shortcut shown from the lock screen, search screen, etc.

For example:

“Hey Siri, show me today’s events in MySportsApp”

From a developers perspective all you need to do is:

  • Define your shortcut with a simple addition to your Info.plist file
  • Donate your shortcut to iOS every time the user performs the specific action associated with the shortcut (either through normal interaction with your app, or through the shortcut)

The “donation” of your shortcut allows Siri to build a usage pattern for how the user interacts with your app. If a particular action is performed a number of times then Siri may offer the user a shortcut to that action (if the app has defined one) on the lock screen or search screen:

The user may also record a “Hey Siri” phrase that triggers your shortcut. We’ll see how this works later on in this post.

When iOS 12 is released a Shortcuts app will be available as a repository to enable easy sharing and discovery of shortcuts.


Siri shortcut limitations

Siri shortcuts are not quite as flexible and powerful as they first appear to promise!

Initially I thought I’d be able to be support actions like:

“Hey Siri, show me a picture of a rabbit in PicSearch

Where rabbit is a parameter to be passed to the target app PicSearch.

Sadly, you can’t (yet) do this sort of thing. As you’ll see, it looks like all the support is in-place to support passing parameters, but Siri isn’t actually capable of it. I’m sure it will come in iOS 13, but for now you are limited to to the creation of very specific actions which are then made accessible by a shortcut.


Overview of how to implement Siri shortcuts

There are two approaches to creating Siri shortcuts:


  • Simple to implement
  • Open your app and trigger an action via a shortcut or Hey Siri phrase
  • Little customisation


  • More complex than NSUserActivity
  • You can customise the experience for the user
  • Open your app and trigger an action via a shortcut or Hey Siri phrase
  • Trigger an action via a shortcut or Hey Siri phrase without opening your app (app extension)
  • Include custom responses from Siri and a custom UI that Siri will present

In this post we’ll concentrate on the NSUserActivity-based approach. In a later post I’ll take a look at a more complex example using Intents.


Overview of the demo app

The following demo app shows how to create a Siri shortcut-enabled app (“PicSearch”) that displays an image using a trigger phrase like:

“Hey Siri, show picture”

The source for the demo app is available on GitHub:



Define a shortcut

In order to create a shortcut you first Define the shortcut and then Donate it.

First, using Xcode create a new single view iOS app (we’ll leave it with all the default content at first).

Select the target and the Capabilities tab, then turn on support for Siri. This adds a .entitlements file to your project and allows you to use to Siri SDK:
Now add a NSUserActivityTypes key to your info.plist file. The single entry in the array is a string consisting of your Bundle ID followed by an identifier for the action that the user will trigger via Siri. In this instance the Bundle ID is com.rarcher.PicSearch and the Siri trigger ID is showPic:
Build the project to make sure there are no errors at this stage.

Donate the Shortcut

You “donate a shortcut” each time the user performs a particular action in your app. This allows Siri to build a picture of how the user interacts with your app. Over time Siri will learn to make that a shortcut available to the user appropriately on the lock screen, Siri Suggestions screen (swipe down from the top of the screen to show), Search screen, etc.

Apple’s documentation states:

“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.”


Tip: In development you can force Siri to immediately display shortcuts by going to Settings > Developer and turning on the options related to shortcuts testing:

Here’s the simple UI for our PicSearch demo app:
The UI consists of just a button to trigger showing an image and a UIImageView.

When the user taps the “Show Picture” button a sample image is displayed and the shortcut donated to iOS (I added three images named “Owl”, “Parrot” and “Penguin” to the asset catalog):

Here’s the code for the app’s ViewController. Notice that all the code is simple boilerplate apart from the donateShortcut() method:
Finally, we need to expose the shortcut’s entry point in our AppDelegate.

Notice how we can check for a particular shortcut through the NSUserActivity activityType member (which we set in the ViewController when donating the shortcut):

Run the app and tap the “Show Picture” button (which donates the shortcut to iOS).

When the shortcut has been donated at least once it becomes available in Settings > Siri & Search > Your App Name, where the user may add a custom “Hey Siri, …” trigger phrase to run the app’s shortcut:

The shortcut may also appear at the top of the Settings > Siri & Search view:
To record your trigger phrase (you’ll need to run the app on a real device to test this) tap the + next to the shortcut in Settings > Siri & Search:
Tap the red record button and say something like “Show picture” or “Show me a picture”:
Siri displays the text for your trigger phrase (“Show picture” in this case).
Tap Done to complete the process:
You can now find that you can launch the app and display a picture simply by saying your trigger phrase:

“Hey Siri, show picture”:

In my next post I’ll look at how to implement more sophisticated Siri shortcuts using Intents.