Discover how you can make key parts of your app available for someone at exactly the right moment — without them ever needing to open it. Learn how to craft and donate intents to the system, helping you surface relevant and contextual information about your app in Siri, Focus, Shortcuts, the Smart Stack, and more. We'll explore how the system intelligently identifies information and show you techniques for structuring intents to help increase engagement and visibility for your app.
♪ Bass music playing ♪ ♪ Ryan Chapman: Hello and welcome to WWDC. Hi, I'm Ryan Chapman, and I work on the Proactive Intelligence team. Today I'll be talking to you about how you can expand your app's presence with intent donations. Our device's operating systems have become increasingly integrated with the apps people use day to day. This collaboration between the system and apps is at the heart of an intelligent system experience that gives our users superpowers. One of the primary ways your apps can participate in this collaboration and expand your app's presence and capabilities throughout the system is by donating intents. In this session, I'll define what intent donations are, walk you through the life of an intent donation, and then talk to you about how you can structure your donations for success and ultimately expand your app's presence across the system. Let's go ahead and start out with understanding what intent donations are. Three years ago in iOS 12, we introduced Shortcuts. Shortcuts let you expose the capabilities of your app as actions. They enable people to use your app's features in new ways and places across the operating system. It's a really powerful way to engage your users and expand your presence beyond the confines of your app. Every action that you expose should be accelerative, by performing 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. And next, every action that you expose should be repeatable and of persistent interest to the user. That means it should be something that the user might want to do multiple times. It's not a good idea to expose an action for something that someone might only want to do once or twice. And you should also only expose actions that are stateless and executable at any time, because you can't rely on someone being in a particular state before your action will be ready for use. To learn more about what makes a great action, be sure to check out the session called, "Design great actions for Shortcuts, Siri, and Suggestions" from WWDC 2021. So once you've decided what actions to expose, you're ready to check out the Shortcuts APIs. There are two APIS that you can use to adopt shortcuts for your app. 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 you can use to integrate with the system. Intents also supports the ability for you to define your own custom intents for use with Shortcuts. To learn more about both APIs and how to adopt shortcuts for your app, be sure to watch the "Introduction to Siri Shortcuts" session at WWDC 2018. For this session, I'll be focusing on Intents, going over new and existing opportunities for you to offer your app's capabilities throughout the system. The first step toward making an intent donation is to decide what type of intent you'd like to adopt. Siri includes many great built-in intents, like for messaging, reservations, media, and more. There is also the ability to define custom intents in Xcode for Shortcuts. So if the action 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 using an intent definition file in Xcode. Once you've decided which intent you'd like to adopt and defined it in your app, you can start making intent donations. An intent donation is the act of telling the system when a person performs an action in your app. The system will store these donations and use them to expand your app's capabilities and presence throughout the system. Apps that donate intents show up in places throughout the system like Suggestions, Shortcuts, Focus, Smart Stack, and Siri. Now that you understand at a high level what an intent donation is, let's make this more concrete by going through the life of an intent donation using an example. Let's use the example of checking the weather in the Weather app. For this app, checking the weather at a particular location is the key capability of the app that I'd like to expose an action for. This app already has an existing widget that I'd like to make configurable using my intent, so someone can select the city they'd like to see the weather for in the widget. Let's go ahead and learn how to define a check weather intent, how to donate it to the system, and how the system uses the donation. The first step to defining an intent in Xcode is to create an intent definition file. To do this, I'll add a new file...
...and select the SiriKit Intent Definition File. Then I'll select any targets that I want to use the custom intent in, and confirm that I'd like to create the intent definition file. Once the intent definition file is created, I can define the intent. There wasn't an existing built-in system intent to check the weather, so I can go ahead and add a new intent. I'll call the intent "Check Weather." From here, I can begin defining the intent. I'll start by checking the "Intent is eligible for widgets" option because I'd like to allow this intent to work as a configuration for my app's existing widget. The system will also be able to use my intent donations to power Smart Stack widget intelligence. If you want your intent to also support the Shortcuts app, check the "Intent is user-configurable in the Shortcuts app and Add to Siri" option. I'll uncheck this option for this demo and just focus on widgets and Suggestions. I'll also leave the "Intent is eligible for Siri Suggestions" option checked because I'd like the system to use my donations to surface Siri Suggestions for my intent. Next I need to define the parameters of my intent. I can define just one parameter for the location to check the weather in. Next I need to select the parameter's type. This location represents an object in my app corresponding to the city the app has the weather for, so I'm going to use a custom type to represent this parameter. I can go ahead and create a custom type for a city that has an identifier and displayString.
Let's go back to our location parameter. You can see that the type of the location is the new custom City type. I'll keep the option for allowing users to edit the value in widgets, because I'd like this intent to be used for widget configuration. Since this intent won't support running in Siri for this demo, I'll uncheck the "Siri can ask for value when run" option. When people configure the widget, the list of weather locations will need to be provided by the app and will change depending on which cities that person has saved so I will check the "Options are provided dynamically" checkbox. Finally, I just need to define the supported parameter combinations for Suggestions. The system reads the intent definition file to determine the intent and parameter combinations that an app supports for prediction. In this case, the app supports an intent with a location parameter set. I'll go ahead and add that parameter as a supported combination. Then I'll define the summary that is shown in Suggestions. And that's it. I've defined the custom intent to check the weather that can be used by widgets and Suggestions. With the intent defined, I just need to donate the intent to the system whenever someone checks the weather for a specific location in the app. To donate the intent, I create an instance of the intent class and set its parameter values. After creating the intent, I create an instance of an INInteraction object, passing in the intent, then call the interaction object's donate method to donate the intent to the system. Behind the scenes, the system stores these donations over time along with the context the person was in when the intent was donated. As they continue to check the weather in the Weather app, the app continues to make intent donations. In this case, they have been checking the weather in Cupertino and in San Diego. The system uses the intent parameters to determine whether the intents are equivalent or not. As shown by the color of the donations, the two Cupertino donations are equivalent and are different from the two San Diego donations. In practice, the system also receives donations from many other apps on the person's device. If at any time you'd like to delete donations, you can delete a single donation or a group of donations using our deletion APIs. If someone has, for example, removed the San Diego weather location from their stored weather locations, then you can delete intents associated with the San Diego location. It's important to delete donations so people don't get suggestions for actions in your app that are no longer relevant. When donating the intent, the INInteraction identifier and group identifier can be used to later delete one or more INInteractions that you've donated. You can either pass in an array of identifiers to delete individual interactions, or you can pass in the group identifier to delete a group of interactions. So how are all of these intent donations used by the system? Let's take a high level view of the donation history the system sees across multiple days. Here you can see three days of donations for a person and the donations that occurred throughout the day, starting with when they woke up. The system uses machine learning and on-device intelligence to find patterns in the data and predict what intent is relevant given a person's current context and past behavioral patterns. In this case, you can see that this person has a pattern associated with checking the weather after they wake up. The on-device intelligence integrates with user-facing features to expose your app's capabilities and presence to the user. Let's look at some examples of where this exposure takes place. Before we do that, it's worth noting that all of the machine learning and intelligence is performed on-device in a privacy-preserving manner, meaning Apple does not collect any data that can be used to personally identify a user. With that said, let's return to our weather example. I can use the intent I defined to make the app's existing widget configurable. After configuring the widget to use the intent, people will be able to select the location they'd like to see the weather for in the widget. With the app donating intents that match the widget's configuration intent, the system is now able to provide people with Smart Stack widget intelligence for the app. Let's say there is a person who has a Home screen configuration with a Smart Stack. New in iOS 15, the Smart Stack supports Widget Suggestions, which allow the system to suggest widgets the user doesn't have in their stack by placing them on top of the stack at just the right time. To determine whether a widget should be suggested and the correct time to make the suggestion, the system leverages the intent donations that match your widget configuration intent. In the weather example, after the person woke up, the Smart Stack placed the Weather widget on the top of the stack at just the right time. This is a great way for people to discover your widget and to deliver glanceable information. If they already had the Weather widget in their stack, then it would have rotated to the Weather widget instead. To learn more about how to add configuration and intelligence to your widgets, watch the WWDC session from 2020. Your intent donations also power the on-device intelligence behind Siri Suggestions that are shown in Lock screen, in Spotlight search, and in the Siri Suggestions widget. These suggestions allow people to perform the key capabilities of your app with one tap. Your intents can also be used in the built-in Shortcuts app as a part of a simple or complex multi-step shortcut across macOS, iOS, and watchOS. And donations are also used to determine what actions get suggested to people in the Shortcuts App Gallery. People can also set up a voice shortcut to execute your custom intents just by asking Siri. If you chose to use the built-in INSendMessageIntent, your intent donations are used by sharing suggestions to make it really easy for users to get content to the people and groups that matter most to them. New in iOS 15, when you donate INSendMessageIntents, the system uses the people in your donations to determine who is strongly associated with the user's current Focus. These strong associations can be used to make suggestions to add certain people to their allowed notifications list when they receive messages from them. In this case, you can see that Aga is suggested as a person who this user should consider adding to their allowed notifications list for Work Focus based on that person's past interactions with Aga. If you choose to use the built-in INGetReservationDetailsIntent, your intent donations will be used to notify users when it's time to leave for their restaurant reservation based on current traffic conditions and when it's time to check in for their flight. People will also see Siri Suggestions when they open Maps, which makes it super convenient to get directions to the airport with just one tap. New in iOS 15, if you choose to use the built-in INPlayMediaIntent, your intent donations will be shown in the new Now Playing UI in Lock screen, Control Center, and in the Home app. This is a fantastic way for users to start listening to or watching their favorite content from your app. People may consume periodical media content like podcasts, TV shows, or movies in your app. In these cases, you can use the INUpcomingMediaManager API to provide the system a list of media intents for content that the user hasn't listened to or watched, so might be interested in. The system combines the past media donations with your app's upcoming media to make better media suggestions. Your intents can also be surfaced on the Siri Watch Face using the INRelevantShortcut API. The INRelevantShortcut API enables you to expose relevance information to the system such as a time or a location for when your shortcut should be shown on the watch face. To learn more about how to expose your shortcuts on the Siri Watch Face, watch the "Siri Shortcuts on the Siri Watch Face" WWDC session from 2018. New in iOS 15, the widgetKind property was added to the INRelevantShortcut object so you can hint to the system when to show the corresponding widget in a Smart Stack. To learn more about this property and how to use it, watch the "Add intelligence to your widgets" session from WWDC 2021. To summarize, we've taken a look at the life of intent donations and seen how they are used to expand your app's presence and capabilities throughout the system to an increasing number of places like the Smart Stack, Focus, Suggestions, Shortcuts, and Siri. Now that we've looked at the life of an intent donation, let's talk in more detail about how you can structure your donations for success and ultimately expand your app's presence across the system. Let's use a new example of ordering coffee in a coffee app. So far I've defined an order coffee intent and exposed two parameters: the size of the coffee and the coffee item. In this case, we have a large iced latte. Let's take a look at what could go wrong if I include the order date in my intent donation. It starts off OK, with a donation coming in for a large iced latte on June 7, 2021. But once the date changes, the intent's date parameter has a new value, and the system treats the second donation as a completely different intent, despite both donations having the same item and size. The system continues to treat the donations differently over time and you can see that they're not equivalent across the days, based on the donation's colors. If you look at a high-level view of the donation history the system sees across multiple days, you can see that there's no meaningful pattern the system can find for ordering a large iced latte. Let's take a look at how I filled out the intent definition file to understand what went wrong. I defined the three parameters for item, size, and date. And I added a supported parameter combination with all three parameters. This tells the system that it should use all three parameters to determine how to find patterns across intent donations for prediction. In this case, including the date in the supported combination with the item and size prevented the system from properly finding a pattern across the donations. To resolve this issue, I can instead define a supported combination that includes only the size and item parameters. By doing this, the system knows that it should only use the item and size parameters when comparing intent donations to find patterns over time. Now, the system will see a donation for a large iced latte, not including the date anymore. Then on the second day, the system sees an equivalent donation for a large iced latte. And same on the third day. If you look at a high-level view of the donation history again, you can see that there is now a pattern associated with ordering a large iced latte just after waking up. To maximize the benefit of your donations, please ensure your intent donations are likely to be repeated and the intent payload you're donating is consistent across donations. That means don't include timestamps. In summary, the system has become increasingly integrated with the apps we use day to day and intent donations are a key integration point. Benefit from donating intents by expanding your app's capabilities and presence across the system. Thank you for listening and I hope you have a great rest of your WWDC 2021. ♪