Siri Shortcuts Tutorial in iOS 12

If you’ve had an iPhone for any length of time, you’ve likely interacted with Siri. When Siri was first announced in 2011, its ability to understand context and meaning, regardless of the specific combination of words used, was groundbreaking.

Unfortunately, Siri integration was limited to Apple’s own apps until the release of SiriKit in 2016. Even then, the types of things you could do with Siri were limited to a particular set of domains.

With the release of Siri Shortcuts in iOS 12, this is no longer the case. Now, you can create custom intents to represent any domain, and you can expose your app’s services directly to Siri.

In this tutorial, you’ll learn how to use these new shortcuts APIs to integrate Siri into a writing app.

Getting Started

To get started, use the Download Materials button at the top or bottom of this tutorial to download the starter project.

Once downloaded, double-click TheBurgeoningWriter.xcodeproj to open the project in Xcode.

Set the bundle ID to something unique to you (Apple recommends using a reverse DNS name such as com.razeware.TheBurgeoningWriter). Then, run the app, and you’ll see a home screen that shows all of the written articles. From here, you can add new articles and publish the drafts you’ve previously saved.

The big idea here is to write an article, sit on it for a little bit, and then publish it later — provided you’re still happy with it.

Ready to begin? Great!

Adding Shortcuts to an App

The first thing to consider is which features of your app are appropriate for turning into shortcuts.

Ideally, you should create shortcuts for actions your user can perform; preferably, something they’ll likely do repeatedly. Once you’ve decided to set up a shortcut, there are two ways to create it:

1. NSUserActivity: User activities are part of an existing API that allows you to expose certain things a user can do for app hand-off and Spotlight searches. The thing to remember here is that this option is only useful when you want the user to go from Siri into your app to complete a task.
2. Custom Intents: Creating a custom intent is the true power of shortcuts. With an intent, you can communicate with your user via Siri without ever having to open your app.

Making a Shortcut for Writing New Articles

Your first shortcut is one that lets a user go straight to the new article screen. This is the perfect candidate for creating a shortcut based on an NSUserActivity object, because it’ll take the user from Siri into your app.

Your goal is to donate one of these activities to the system every time your user performs that action. You’ll do so by adding a new method that allows you to generate these activity objects.

Open Article.swift and, at the top of the file under the imports, add the following constant string definition:

public let kNewArticleActivityType = "com.razeware.NewArticle"

This is the identifier you’ll use to determine if you’re dealing with a “new article” shortcut. A good rule of thumb is to use the reverse DNS convention when choosing an identifier for your shortcut.

Next, below the properties, add the following method definition:

public static func newArticleShortcut(thumbnail: UIImage?) -> NSUserActivity {
  let activity = NSUserActivity(activityType: kNewArticleActivityType)
  activity.persistentIdentifier = 
    NSUserActivityPersistentIdentifier(kNewArticleActivityType)

  return activity
}

Here, you’re creating an activity object with the correct identifier and returning it. The persistentIdentifier is what connects all of these shortcuts as one activity.

For your activity to be useful, you have to do some configuration.

Add the following two lines before the return:

activity.isEligibleForSearch = true
activity.isEligibleForPrediction = true

First, you set isEligibleForSearch to true. This allows users to search for this feature in Spotlight. You then set isEligibleForPrediction to true so prediction works. Setting this to true allows Siri to look at the activity and suggest it to your users in the future. It’s also what allows the activity to be turned into a Shortcut later.

Next, you’ll set the properties that affect how your Shortcut looks to users.

Define a local attributes property. Add it below the previously pasted lines:

let attributes = CSSearchableItemAttributeSet(itemContentType: kUTTypeItem as String)

Set your attributes by adding the following lines:

activity.title = "Write a new article"
attributes.contentDescription = "Get those creative juices flowing!"
attributes.thumbnailData = thumbnail?.jpegData(compressionQuality: 1.0)

This sets the title, subtitle and thumbnail image you’ll see on the suggestion notification.

Stepping back for a moment, it’s important to remember that Siri exposes this feature in two separate ways:

• First, Siri learns to predict what your users might want to do in the form of suggestions that pop up in Notification Center and Spotlight Search.
• Second, your users can turn these activities into voice-based shortcuts.

For the last bit of configuration, add the suggested phrase users should consider when making a shortcut for this activity:

activity.suggestedInvocationPhrase = "Time to write!"

The chosen phrase should be something that’s short and easy to remember. It should also not include the phrase “Hey, Siri” because the user might have already triggered Siri’s interface that way.

Finally, assign the attributes object to the activity object:

activity.contentAttributeSet = attributes

Now that you can grab user activity objects from an Article, it’s time to use them.

Using the Activity Object

Open ArticleFeedViewController.swift and locate newArticleWasTapped().

Below the comment, add the following lines:

//1
let activity = Article.newArticleShortcut(thumbnail: UIImage(named: "notePad"))
vc.userActivity = activity

//2
activity.becomeCurrent()

1. First, you create an activity object. Then, you attach it to the view controller that’ll be on screen.
2. Next, you call becomeCurrent() to officially become the “current” activity. This is the method that registers your activity with the system.

Congratulations, you’re now successfully donating this activity to Siri.

Build and run. Then, go to the new article screen and back to the home screen a few times.

You won’t see anything too interesting in the app, but each time you perform that action, you’re donating an activity to the system.

To verify, pull down on the home screen to go to search. Then, type “write”, and you should see the “Write a new article” action come up.