Introduction to Siri Shortcuts

Hi, everybody. My name is Ari Weinstein, and I'm really excited to be here along with Willem Mattelaer to tell you about Siri Shortcuts. So, two years ago, we announced the first version of SiriKit, which enables your apps to work with Siri, and it has great domain-specific knowledge for things like sending messages, requesting rides, making payments, and more. But we know that you want to do even more with SiriKit, and so that's why, this year, we're so excited to announce Shortcuts.

This central idea behind Shortcuts is that it lets you expose the key capabilities of your app to Siri, and this is really great, because it enables people to use the features of your apps in new ways and in new places. And it's a really powerful way to engage your users.

So, exposing a shortcut opens up a ton of new possibilities for how people can use your apps, so let's explore all of the places where Shortcuts can be used. Shortcuts takes Siri's suggestions to the next level by surfacing what you want to do next, not just with your apps, but inside of your apps, and it does it by surfacing them in search at just the right time.

And Siri can suggest shortcuts on the Watch, so you can use them right from your wrist on the Siri Watch Face.

When Siri is confident that it's the exact right time for a Shortcut, it will be surfaced on the lock screen. And, when you tap on a shortcut, you can use it right in line with a rich custom UI specific to that app. And you can also add shortcuts to Siri, so you can use them with your voice just by asking Siri. And in Siri you'll see the same custom UI that you see in search and on the lock screen.

And apps can provide a great voice experience in Siri by providing custom response dialog that Siri will read out loud to tell you things like how long it will take for your coffee to be ready. So, when the user adds a shortcut to Siri, they get to pick a custom personal phrase, so the user chooses what to say to Siri to invoke your shortcut. And, as a developer, you get to suggest what phrase to use, so, in this case, a suggestion is "coffee time." And, once a shortcut has been added to Siri, it works across all of your iOS devices, and on Apple Watch, and even on HomePod. So, we also have the new Shortcuts app, and with the new Shortcuts app, anyone can build their own shortcuts, and you do it just by dragging and dropping a series of steps together. And those steps can even include the shortcuts exposed by your app. So, today, we're going to talk about how to adopt shortcuts for your apps, and then we'll talk about how to optimize your shortcuts for great suggestions. And we'll also cover some privacy considerations that are important to keep in mind, and we'll talk about how to make great shortcuts for media playback.

So, first, we'll talk about how to adopt the new Shortcut's APIs.

There were three steps for creating a shortcut, and the first step is to define your shortcut. That means you have to decide what you want to expose as a shortcut and define each one so Siri knows everything that your app can do.

Next, you'll need to donate your new shortcut. That means you need to tell the system every time the user does something in your app that you expose a shortcut for, which will let Siri learn when and where is the right time to suggest your shortcut. And the third step is to handle your shortcut. That means, when the user wants to go and use your shortcut in Siri, on the lock screen, in search, you need to be ready for your app or app extension to be invoked and be handed the shortcut to handle.

So, before you define shortcuts, you'll need to decide what exactly it is that you want to expose. And you should start by thinking through what are the most important things that people like to do with your apps? Because those are the things that you might want to consider exposing shortcuts for. So, every shortcut that you expose should accelerate the user, to perform a key function of your app. That means it should take something that the user already wanted to do with your app and help them do it even faster.

The acceleration that you offer should be substantial, so you shouldn't just expose a shortcut that does about the same thing as opening your app normally. If you expose a shortcut that doesn't provide very much acceleration to the user, it won't be suggested as frequently. And, next, every shortcut that you expose should be of persistent interest to the user, so that means it should be something that the user might want to do multiple times. It's not a good idea to expose a shortcut for something that the user might only want to use once or twice. And you should also expose only shortcuts that are executable at any time, because you can't rely on the user being in some particular state before your shortcut will be ready for use.

So, once you've decided what shortcuts to expose, you're ready to check out the shortcuts' APIs.

There were two APIs that we support for adopting shortcuts. The first is NSUserActivity. NSUserActivity is a lightweight way to represent the state of your app, and it integrates with other Apple features like Spotlight and Handoff.

And the second is intents. Intents are a way of representing, in detail, a type of action that your app can perform, and Siri includes a bunch of great built-in intents that support a range of capabilities that apps can use to integrate with Siri. And, this year, we're introducing something really cool, which is the ability for you to define your own custom intents for use with Shortcuts.

So, for every shortcut you expose, you'll need to decide whether it should be an NSUserActivity or an intent. So, let's talk about how to make that decision.

Now, NSUserActivity is a great choice for building a shortcut. If you're just building a simple shortcut that opens something in your app, or if you're exposing a shortcut for something that you already index in Spotlight search, or that you already offer in NSUserActivity for, for example, for Handoff. But for the best Shortcuts experience, you'll want to adopt intents, and intents-based shortcuts are really cool, because they can run inline without launching your app. And they can include custom voice responses and custom UIs like we saw earlier. And they can also include granular parameter predictions, which Willem tell you a little bit about later.

So, once you've decided how to adopt, you're ready to dive into the implementation, so let's do that now. First, let's go over how to adopt shortcuts with NSUserActivity, and the first step is to define your shortcut. For NSUserActivity, that means you need to declare a UserActivityType in your app's Info.plist file to register your activity type with the system.

Next, you need to donate your shortcut. For NSUserActivity, that means every time the user is looking at the screen in your app that you want to provide a shortcut to, you should make an NSUserActivity object available.

So, there's one key new thing here, which is the isEligibleForPrediction flag. Setting this on any user activity turns it into a shortcut, and what's really cool is if you have an existing user activity in your app, you just have to set this to true and that user activity will become a shortcut automatically.

Now, note that the isEligibleForSearch flag has to be true in order for isEligibleForPrediction to have an effect. And, by the way, you might also want to consider the isEligibleForHandoff flag, which defaults to true. So, by default, all of your user activities will be able to be handed off between devices. Now, when you're creating your user activity, you want to make sure to include all of the information in your user info dictionary that you'll need to restore the activity later on.

And the last step is to mark your activity current by attaching it to a UI viewController or a UI responder object that's onscreen. Now, the last step is to handle your shortcut, once you've defined and donated it. And every time the user uses an NSUserActivity from your app, it will be opened in your app. And so you need to handle it by implementing the app delegate method for handling NSUserActivity, which is called continueUserActivity. So, all you have to do is implement this method, check if the activity type matches the one that you registered, and, if it does, then you want to restore the state of your app to what it was when the user activity was saved.

So, that's everything you need to do to get Siri to start suggesting shortcuts for your apps with NSUserActivity.

Now, let's talk about how to expose Shortcuts through intents.

The first step, again, is to define your shortcut. And so with intents, you'll need to start by deciding what type of intent you'd like to adopt. And, as you know, Siri includes many great built-in intents, like for messaging, workouts, lists, and more.

And now we're introducing the ability to define custom intents in Xcode for Shortcuts.

And so if the shortcut that you want to build corresponds to one of the default built-in SiriKit intents, then you should adopt that. But, otherwise, you can define your own. And whether you want to define your own or adopt an existing one to customize it, you want to get started by creating an intent definition file in Xcode. So, believe it or not, in my spare time, I've been working with a couple friends on a new app, and it's a soup delivery app, and it's called Soup Chef. It's the easiest way to order soup, and I'm really excited about the potential of hooking it up to Siri. So, let's step through how to use the new Intent Editor to build an intent for Soup Chef. I'm going to start by going to File, New File in Xcode, and I'll choose the SiriKit Intent Definition File type. And then I'll see the new Intent Editor. So, let's get started by clicking the plus button in the bottom left. Next, I want to give my intent a name. And, so in this case, I'm making an intent for ordering a soup, so I'm going to call it OrderSoup.

Then I want to fill out my intent's metadata. So, let's look at that one step at a time.

The first piece of metadata is category and defining a category helps Siri know how to talk about your intent and how to display it in the UI. So, for example, in this case, I'm choosing the Order category, and when I choose Order, Siri will say something like, "Okay, I ordered it," when I use it with Siri. And it'll display a button confirmation title like Order. So, we offer several different categories, and you should choose the one that matches your intent's purpose the most closely.

Next, you want to fill out your intent's title and description, and that will be used in all the places where people can discover which shortcuts your app supports.

And then there's the User confirmation required checkbox, which determines whether or not we'll ask the user for a confirmation before using your shortcut. So, Siri might say something like, "Are you ready to order with Soup Chef?" That's really great for my app, because I want to make sure that people aren't accidentally ordering soup .

So, then, you'll see the intense parameters. And these define all of the parameters that are passed to your shortcut. For example, in my case, I have two parameters. They are the list of items being ordered and the location to deliver to. Now, parameters support a short list of types, and those types include things like string, number, person, and location. But if you're building a parameter that represents an object that's in your app that's not on the short list of types then you can choose the custom type. Once you've defined your parameters, you'll want to look at shortcut types. These define all of the types of shortcuts that you'd like to be suggested to the user.

Each type includes a particular combination of parameters that will be predicted, and formats for how to display the title and subtitle of each one, filling in the values for your parameters. So, if your shortcut can't be performed in the background because it needs to launch your app when you use it, you should uncheck the Supports background execution checkbox. Now, in some cases, one intent may have multiple shortcut types, where some support background execution and some don't. Now, in the case of Soup Chef, that's especially relevant, because we can support background execution when both the items and delivery location are predicted, because we have all we need to place an order. But if we add a shortcut type that only includes delivery location, Siri may predict that, and we won't actually have enough information to place an order. So, we'll need our app to open to ask the user what location to deliver to, and, in that case, we'll want to not support background execution for that shortcut type. Now, you should specify shortcut types for every variation of your shortcut that you think will be useful so that Siri can make the best predictions. And, for the best experience, you should-- on all the shortcut types, you can-- support background execution. Shortcut types that support background execution provide more acceleration to the user, and so they'll actually be suggested more frequently.

You can provide up to 16 shortcut types for every intent that you define.

Now, once your intent is defined, Xcode will automatically code generate an intent class and an intent handling protocol. In my case, we've generated the OrderSoupIntent class and an OrderSoupIntentHandling protocol with properties that correspond to what I just defined in my intent definition file. Because Xcode is doing code generation, it's really important to consider in which targets Xcode is doing this code generation, because you don't want to end up with duplicate instances of the same classes that conflict with each other.

So, let's look at the targets in the target membership section of the inspector on my intent definition file.

Your intent definition file should be included in every target in which your intent is used, so you should check the box under Target Membership. But you'll want to make sure that if you have a framework, you don't do code generation in multiple targets that are included from each other. So, if you have a framework, set the target membership to only generate intent classes for that framework by choosing intent classes and choosing no generated classes for every other target. But if you don't have any frameworks in your app because you haven't separated your app into frameworks yet, you should check the target for every single target.

And that's how you define custom intents in Xcode.

Once you've defined your custom intent, it's really easy to donate it. All you have to do is instantiate your intent object and then populate its parameters and create and donate an INInteraction object.

Make sure to do this every time the user performs the equivalent of your shortcut in your app. In this case, every time the user orders soup, I want to donate this intent, because that's going to help Siri learn when is the best time to predict it? So, all that's left, now that we've defined our custom intent, is to handle it. And, just like with NSUserActivity, you should implement the continueUserActivity method in your app delegate in order to handle your intent. So, when an intent is opened in your app, it's passed in as an NSUserActivity object, whose activity type is the name of the intent class that you generated earlier. In this case, it's OrderSoupIntent.

But if you only implement continueUserActivity, your shortcut will open your app every time. It won't run in the background, or work inline in Siri, or support things like custom voice responses. So, for the best experience, you want to create an extension to handle your shortcut in the background.

And to do that, create a new target in your Xcode project and choose the Intents Extension template. Make your intent handler conform to the intent handling protocol. In this case, it's OrderSoupIntent handling and then implement these methods, which are confirm and handle. Now, note that unlike traditional SiriKit, you don't need to implement any resolve methods, because your intent is ready to go without any customization needed or any follow-ups from the user. So, in confirm, you should check all of the values of the properties of your intent to make sure that they're valid. And, if they're not, you should return an error code if you don't think you'll be able to handle that intent. And then you should handle, actually perform your shortcut. So, in this case, that means actually placing an order for the soup. And then you return a response object that indicates the outcome, such as success.

Again, you should implement an intents extension for every shortcut that can run in the background, because then they'll run right in line inside of Siri, on the lock screen, in search, in the Shortcuts app, and on the Siri Watch Face, without having to launch your app. The most valuable shortcuts are the ones that run in the background, but you can also build a lot of great other shortcuts. And keep in mind that, even if you implement an intents extension, you should always implement continueUserActivity, because the user will have the opportunity to open the shortcut in your app from Siri, for example, by tapping on the card in Siri that shows your apps' custom UI. So, there's one more thing that I want to tell you about, which is INRelevantShortcut. Now, INRelevantShortcut is the way to expose shortcuts to the Siri Watch Face, and you do it just by providing INRelevantShortcut objects that include your intents or user activities.

You can, optionally, include relevance information in your relevant shortcuts, which is a hint to the Siri Watch Face as to when your shortcuts will be relevant and when's the best time to show your shortcut? Now, the really cool thing about INRelevantShortcut is that it works even if you don't have a Watch app. So, you can actually expose relevant shortcuts from your iOS apps, and if they run in the background, they'll appear right on the Siri Watch Face. Okay, now that we've explored all the ways that Shortcuts can be used and how to adopt the APIs, I'm going to turn it over to my colleague Willem who's going to give you a great demo of how to adopt shortcuts in Xcode.

Willem? Thanks, Ari.

I'm so excited to be the first one to demo adopting Shortcuts. Before I dive into Xcode, let me show you the app we've been working on. As Ari mentioned, we've been working on a soup-ordering app called Soup Chef. Let me show it to you.

So, this is Soup Chef. When I launch the app, I'm presented with my order history. Since I haven't ordered anything yet, this is still empty. I can place a new order by tapping the plus button.

This presents me with the soup menu, where you can see the available soups I can order. Let's order a tomato soup. Next, I can specify the quantity and options for my soup. I'll order a single tomato soup with red pepper, and when I'm ready to order, I tap the Place Order button.

I'm brought back to the order history where you can now see the order that I just placed. I can tap the order to see more details about a specific order.

This view has an associated user activity. I think it would be pretty cool to suggest this to our users, since our users like to reminisce about the good soups they've ordered in the past . And it would be great if this could be suggested to them. So, let's go to Xcode and see how we can do that.

Here, I'm looking at the viewController for the order detail view.

I'm creating a user activity, and I'm setting the requiredUserInfoKeys. I'm also making sure that it's EligibleForSearch.

For it to be suggested, I also need to make it eligible for prediction.

And that's it. Let's try it out.

First, I need to make sure that I donate the user activity, so I'll go back to the view. That should be enough. Now we want to make sure that the donation actually happened, and, to do that, we added two new developer settings that make it super easy to see a recent donations in search and on the lock screen. To enable it, I go to Settings, and I scroll down to the developer section.

At the bottom, there are two new toggles, Display Recent Shortcuts and Display Donations on Lock Screen. Let's enable both.

I can now go back to the home screen and pull down to go to search, and I see the donation that I just did.

Great.

I can tap it, and the app is launched with that user activity, and I'm back to the order that I was just donated. Great. So, this is pretty good, but I think we can do a lot more. Since the main capability of our app is ordering soup, it would be great if this could be suggested to our users. And I want users to be able to do that without having to launch the app. So, I'll implement it using an intent. There isn't a built-in soup order intent, but now in iOS 12, I can create a custom intent, so I'll do that.

And to start by creating an intent definition file, I'll go to File, View. File and select the SiriKit and then definition file.

Click Next.

Now I can give it a name. I'll keep it to Intents, and I'll put it in the Resources group. All right, and I'm ready. I click Create.

I'm presented with our intent definition file and our new Intent Editor.

Before I add the intent, I'll make sure to include the intent definition file in the right targets. As Ari said, we need to add it to all the targets where the intents are used. So, I'll add it to our shared framework, and, since we're using a shared framework, I don't want it to generate go for app target. So, in the dropdown, next to the app target, I'll select No generated classes.

Now that that's done, we're ready to add our intent. I'll click the plus button in the lower left corner and select New Intent.

I'll give it a name OrderSoup.

Next, I'll select the category. In this case, it's an order intent. Fill out the title, OrderSoup, and the description, Order a soup from Soup Chef.

Since this involves a real-world transaction, I want to use it to confirm this order before placing it, so I'll select User confirmation required.

Next, let's define the parameters. I'm going to define three parameters, one for the soup, one for the quantity, and one for the options that the user selects. I'll start with soup. I click the plus button in the parameter section and fill out the name, soup. Since soup is a custom object of our app, I'm going to select the custom type. Next, I'll add quantity. I click plus again, fill out the name, and this is going to be an integer.

Next, options.

Again, options is a custom object of our app, so I'll use the custom type.

And since the user can select multiple options, I'll also check the array checkbox.

Finally, we need to define the shortcut types. At this point, I'm just going to define a single shortcut type that contains all the parameters.

I'll click the plus button in the shortcut type section and select the parameters I want to include in the shortcut type, so I'll select soup, quantity and options. When I'm ready, I click the Add Shortcut Type button.

I fill out the title Order, and then I'm going to insert the quantity and the soup with options, and I'll leave the subtitle empty, because I've already conveyed all the information I need to in the title. I'll also leave Support background execution checked, because I want the user to run this intent in the background. So, we just defined our first intent. Let's start using it. I'll start by adding two helper methods to our order object to make it easier to convert between it and the intent.

I'll go to the order class and, at the bottom, I'll add an order extension. It contains a computer variable that returns an intent. In it, I create the intent. I set the soup quantity and options, and I return the intent.

Extension also defines a new initializer that dates an intent. In it, I extract the soup, quantity, and options, and then I initialize the order with those values.

Great, this will be very helpful.

Next, we need to make sure that we donate the intent every time the user places an order. So, I'll go to the soup order data manager, and, in the placeOrder method, I'll add our donation logic.

I create an INInteraction that contains the intent of the order, and then I just donate that interaction, and that's it.

Finally, we need to handle the intent. I'll start by adding support in the app itself, so I'll go to the AppDelegate, and, in the continueUserActivity, I'll add support for it. I check if the activityType of the userActivity is equal to the class name of the intent that I want to handle. If that's the case, I extract the intent from the userActivity, and I generate an order with it. Finally, I present the order view. So, since we're launching the app, I'm assuming that the user doesn't want to immediately place the order but wants to make some customizations before placing it, so that's why I'm presenting the order view instead. And, finally, let's add support with an intents extension so the user can run this intent in the background.

I'll need to add an intents extension first, so I'll go to File, View, Target and select the Intents Extension target.

I'll give it a name, SoupChefIntents, and I click Finish.

Since I've added a new target where I'll use the intents, I need to make sure that the intent definition file is included in that target. So, I go back to the intent definition file and add it to that target. Again, I don't want to generate code in that target, so, in the dropdown, I'll select No generated classes.

I also want the extension to have access to the same data as the app, so I'll add it to the same app group.

In the Project Settings, I select the intents target and in the capability step, I'll add it to the same app group. Great. Now, we're ready to implement the intent handler that was created with this target.

First, I'll import our shared framework, SoupKit .

Since we're going to handle the OrderSoupIntent, this intent handler needs to conform to the OrderSoupIntentHandling protocol.

This was generated as part of our intent.

This protocol has one required method, the handle method. Let's implement it. In the handle method, I get an intent. I create an order from that intent, and, if that succeeds, I place the order, and I call the completion with an intent response with a success code. If I'm unable to create an order from the intent, I call completion with an intent response with a failure code. And that's it. I've just added support for a new intent in my app. Let's try it out.

First, I'll need to donate the intent. So, I'll place another order. Click the plus button and this time I'm going to order a clam chowder with croutons, and I'll place the order.

Now, if we go back to the home screen and pull down, I see my donated intent. Great. I can tap it, and I'm presented with a shortcut view and the order button. If I tap the order button, the order will be placed in the background, and it's ordered.

I can go back to the app and see if it was actually ordered, and, yeah, there is a new order in my app. Great, so easy. I can also, instead of tapping the order button, tap the shortcut view, itself, which will launch the app with the shortcut, and, as I implemented it, it shows the order view, where I can customize the order. So, I'll add cheese, too. Who knows? And I'll place the order.

Great. Finally, let's add the shortcut to Siri.

I'll go to Settings, and I scroll up to the Siri and search.

Here I can select the shortcut that I want to add to Siri. In this case, I'll add the order one clam chowder with croutons.

When I tap the record button, I can say the phrase I want to associate with the shortcut. Soup time.

Now, they got it. Let's take a step back and look at what we just did. We started by making an NSUserActivity that was already implemented in our app eligible for prediction. This allowed it to be suggested and is a really easy way to expose the content of your app.

Next, we defined a custom intent. This is really the best way to represent a piece of key functionality of your app. In our case, that was ordering a soup. After defining the intent, we made sure that we donate the intent every time the user placed an order inside of the app. And, finally, we handled the intent, both in an extension to support background execution and in the app itself so the user can launch the app with the shortcut.

So, now that we've seen how you can adopt shortcuts, let's take a look at how those shortcuts are suggested and what you can do to make sure your users see the best possible suggestions. Every time a user performs an action in your app and your app donates this, the system will look at the time, location, and other signals.

For a time, we consider, among other things, the time of day and the day of the week. Well, for the location, we look at the overall location of the user and see if it's a significant location for that user. Let's see how the system now uses these to make a suggestion.

Here, we'll just consider the time. Monday, at lunch, I order a tomato soup with croutons.

That evening, I don't feel like croutons, so I order a tomato with red pepper instead. Next day at lunch, I, again, order a tomato soup with croutons.

I keep doing this throughout the week, and, on Friday, at lunch, Siri might try to find a suggestion for me.

It will look at my past behavior and try to find a pattern in it. And since it's lunchtime, and I usually order a tomato soup with croutons at lunchtime, Siri might notice this and suggest this to me, which is great. It's exactly what I wanted.

So, this is all pretty high level, so let's take a look at how it actually works, starting with NSUserActivity. Imagine a user activity for the place order screen in Soup Chef. The user info dictionary could contain three keys, soup, quantity, and scroll position. The last one is there, so, in Handoff, you can bring the user back to the exact position they were last in.

Let's take a look at how this can be suggested to the user. We start by donating a user activity where the soup is tomato, the quantity is 1, and the scroll position is 79 points. Next, we donate a similar user activity, but now scroll position is changed to 110 points.

We keep doing this, and, at some point, Siri will try to find a suggestion again. It will look at past behavior and try to find a pattern of equal user activities. But since the scroll position is so inconsistent over time, it might not be able to find a suggestion.

So, how can we fix this? We can use the requiredUserInfoKeys.

RequiredUserInfoKeys is an existing property of a user activity. It represents the minimal amount of information that is necessary to restore the app to the state that the user activity represents. And for suggestions it will be used to determine which keys of the user info dictionary will be used to compare when looking for patterns.

Let's apply this to a previous example.

Now we specify that requiredUserInfoKeys are soup and quantity. Again, we donate the user activity where the soup is tomato, the quantity is 1, and the scroll position is 79 points. But now the scroll position will be ignored.

Next, we donate something similar, and, again, the scroll position is ignored.

We keep doing this, and, at some point, Siri will try suggestion again.

Now, I will look back and try to find a pattern of equal user activities. And since it's no longer considering the scroll position, it might be able to say, "An NSUserActivity with soup tomato and quantity 1 is a good suggestion for this user." So, as you just saw, it's really important to specify the right set of keys as being required. Otherwise, your users might not get any suggestions at all. So, that's how it worked for user activity.

Intents work similarly but offer you a lot more flexibility.

The main signal for intents are the shortcut types that you define.

Each shortcut type defines a combination of parameters that is valid for suggestion. It's similar to the requiredUserInfoKeys, but instead of having just one set, you can define multiple. Let's apply this to our Soup Chef app. Earlier, I defined an OrderSoupIntent with three parameters, soup, quantity, and options. At the time, I only defined a single shortcut type that combined all of these parameters, but, ideally, you would define more shortcut types, since that gives more options to the system to find patterns in your user's behavior. So, now I'll define three.

One shortcut type that combines soup and quantity, one that combines soup and options, and one that combines all three parameters.

Let's apply this to another example.

Again, I start on Monday, at lunch, by ordering a tomato soup with croutons.

The Soup Chef app donates this to the system, and the system will split us up into all the possible combinations based on the shortcut types that I just defined. That evening, I order a tomato soup with red pepper. Again, it gets donated, and it will be split up in all the possible combinations.

Next day, at lunch, I order a tomato soup with croutons. It gets donated and split up. I keep doing this throughout the week, and, on Friday, at lunch, Siri might try to find a suggestion.

It might see that I often order a single tomato soup.

But since it's lunchtime, it also can see that, at lunchtime, usually order a tomato soup with croutons.

Since that is a more specific shortcut, it will end up preferring to suggest that. So, I might get a suggestion to order a tomato soup with croutons. Great. So, that's how suggestions are made.

Let's now take a look at how to make sure those suggestions are good, and it all starts from making good donations. A good donation should be something that is likely to be repeated.

For user activity, there could be some content they might look at often. Or, for an intent, there could be an action the user would take regularly. You should make sure that the payload of what you're donating is consistent across all your donations, since that is what will be compared when looking for patterns. A good donation should also not include a timestamp, since that might not longer be relevant by the time this donation would be suggested.

For instance, a shortcut that shows appointments for a specific day is probably not that useful, since, if you see that the next day or later, you're probably no longer interested in the meetings of that specific day.

A shortcut with a relative time, however, is a lot more useful. You should also make sure that you donate exactly once for each user action, even if that user action involves multiple actions inside your app. Finally, selecting the correct parameters of your intent is also important. So, let's take a look at two possible types, starting with enums. You can define enums in your intent definition file next to your intents, and use it as the types of your parameters. We recommend that you use enums whenever the values for a parameter are bounded. For instance, if you would add a size parameter to a order soup intent, it might make sense to make that an enum, since the possible sizes are probably just small, medium, and large.

Using an enum will lead to better suggestions and clearer titles and subtitles for your users.

To learn more about how enums are used to generate titles and subtitles, I recommend that you watch the localization session. Another type you can use is the custom type.

Using a custom type will result in an INObject and your generated intent code.

An INObject combines an identifier with a display string. The identifier can be used to refer to an object internal to your app, while the display string contains the user readable representation of that object.

That way both your users and your app always understands what the value of this parameter is.

Finally, using an INObject also prevents the possible dependency between parameters. Let me illustrate that. There are two ways to represent the combination of an identifier with a display string. You could add two parameters to your intent, one for the identifier, one for the display string, or you could add a single parameter using the INObject. With the first approach, you have a dependency. Since the display string depends on the object as referenced by the identifier, we discourage having these dependencies as they could cause issues when we suggest this intent later. A good shortcut should also have an understandable title, subtitle, and image. It should represent what will happen when the user taps the shortcut, since it will be the only thing the user will see before interacting with it. And, of course, you want to test your shortcuts to make sure that they look right and that they behave as expected. There are a couple of ways to do that. As I showed you earlier, we added two new developer settings that allow you to see your recent donations on search and on the lock screen, instead of your regular Siri suggestions.

By enabling these, you can see what your users will see when those donations would be suggested, and you can try interacting with them to make sure that they behave as expected. Another way to test your shortcuts is by adding them to Siri. An easy way to test them then is by editing the Xcode scheme to automatically invoke Siri without constantly having to say the phrase.

In the scheme editor of an intents extension there is the Siri Intent Query field that you can use to provide the utterance to invoke Siri with. And, finally, you can create a custom shortcut in the Shortcuts app that uses your shortcut.

This allows you to test the behavior of your shortcut when it's chained together with other shortcuts or steps from the Shortcuts app.

So, now that we've seen what a good shortcut donation is and how does donation get suggested to your users, let's take a look at a couple of privacy considerations and how you can make sure your user are never upset by what is suggested to them.

Your users expect that when they delete something from within your app that it's deleted for good. It's important to honor this so you maintain your users' trust and your so users aren't presented with suggestions for things that are not relevant to them anymore.

So, if you donate shortcuts that contain information that the user can delete, you should make sure to delete those donations at the appropriate time. Let's take a look at how to delete donations, starting with NSUserActivity.

There are two ways to delete a donated user activity.

If you use Spotlight indexing and you set the relatedUniqueIdentifier, then deleting the content from Spotlight will automatically delete the donated user activity.

Just set the relatedUniqueIdentifier on the contentAttributeSet to the identifier of the searchable item that it matches with.

Then, when that searchable item would be deleted, it would automatically delete the user activity. If you don't use Spotlight indexing, you can use the persistent identifier property on NSUserActivity. This is a new property that you can set so you can keep track of your user activities and delete them at the appropriate time.

To use it, just set the persistentIdentifier property before donating user activity.

Then, when you want to delete it, you call deleteSavedUserActivities with the identifiers that you want to delete. You can also delete all your donated user activities.

For instance, when your user logs out, you can do that by calling deleteAllSavedUserActivities.

Intents have an existing API, which is similar to this new user activity API.

Since you donate intents through INInteraction the leading and donated intent also happens through INInteraction.

An INInteraction has an identifier and a group identifier property that you can set and then later use to delete one or more donated interactions. Just set the identifier and or group identifier before donating the interaction.

Then, when you want to delete it, you call delete with an array of the identifiers that you want to delete.

You can also delete all donated intents with a shared group identifier by calling delete with the group identifier. And, finally, just like NSUserActivity, there is a way to delete all your donated intents by calling deleteAll on INInteraction.

Please make sure to delete your donations at the appropriate time. This will give your users the best possible suggestions and never make them wonder why they're seeing suggestions for things that are no longer relevant to them.

So, now that we've looked at different things to consider when creating and donating shortcuts, let's end by briefly looking at what you can use to create the best possible media shortcuts. We created a new intent that works great with Shortcuts. This intent is called INPlayMediaIntent and allows you to create and donate shortcuts to play audio or video content.

When handling this intent in your extension, you can choose to have it handled by your app in the background . This allows you to start audio playback straight from your app.

Besides being suggested in search and on the lock screen, shortcuts with this intent will also be suggested in the playback controls on the lock screen when the user connects their headphones, making it even easier for them to start listening to your content.

And, finally, shortcuts with this intent work great on the HomePod.

Just add a play media shortcut to Siri on your iPhone and invoke it on your HomePod. The audio will start playing from your phone through HomePod.

We also created a new API that allows you tell the system about new content they might be interested in.

This is great for periodical content, where the content that you would want to be suggested to your users isn't something they've listened to or watched before.

So, those are a couple of things that we have added to make great media shortcuts.

Now, let's summarize what we just talked about.

Shortcuts enable powerful, new experiences with your apps. It provides new ways to engage your users by exposing your app throughout the system in a variety of places. So, just search the lock screen, the Siri Watch Face on your Apple Watch, and in Siri itself. You can also use it in the new shortcuts app.

You can adopt shortcuts by using NSUserActivity, which is a really easy way to expose the content of your app.

Or you can use intents which provides you with a deeper integration in the system and can unlock entirely new experiences for your users. For more information, our session is 211, and you can find our page on developer.apple.com. You can also find us in the labs throughout the week. Thank you so much for coming. And we can't wait to see what shortcuts you'll create. Enjoy the rest of your conference. [ Applause ]