Provide a continuous user experience by capturing information from your app and displaying this information as proactive suggestions across the system.
- iOS 13.0+
- Xcode 11.0+
This sample app shows a list of pizza restaurants, near your current location, in a table view. Select a restaurant from the table view to donate its location information to the system as a user activity object. The system then displays the registered location information proactively as suggestions, such as in Search, used with Siri Shortcuts.
When a user interacts with a proactive suggestion, the system continues the activity by associating the object’s activity type with the sample app.
When donating location information, this sample app also verifies whether the previously captured information appears, as QuickType keyboard suggestions, within other apps installed on a device.
Declare a User Activity Type
You implement proactive suggestions by determining specific activities that a user can perform in your app, and whose state you can recreate at a later time. The sample app has one user activity,
view-location, which represents the user viewing details of a specific restaurant location.
In the sample app, the target includes the
view-location activity in its Information Property List file, as an entry with the key name
NSUserActivityTypes. The type of this entry is
Array, and each member is a
String representing a supported user activity in reverse DNS notation.
Manage a User Activity
At runtime, you represent a user activity with the
NSUser object. You initialize a user activity object with a string identifier, the same one declared earlier in the
In the sample app,
Location manages a single
NSUser object, representing the
view-location activity type. When you select a restaurant, the view controller sets its
user property to the
view-location activity—registering the user activity object as the current activity, replacing any other activity previously sent to Siri or the system.
The view controller also sets
true, indicating that the activity will be updated with new data in the future, which eventually results in a callback to the
update method. This is the app’s opportunity to refresh the activity object’s
user property, with the minimal amount of information needed to restore the state of the app, before Siri or the system receives the activity.
Provide Support for Improved Search Results
If your user activity objects contain information that the user might want to search for later, you can have Search index those objects and consider them during subsequent on-device searches.
To enable support for Search on a user activity object, set the
eligible property to
true. Additionally, you can make an activity object publicly accessible to all iOS users by setting the
eligible property to
Provide the activity object with as much rich information about the activity as possible, by configuring the
webpage properties so that the system can index the object. The app must also maintain a strong reference to any activity objects that the system uses for search results.
To learn more about Search, see App Search Programming Guide.
Provide Support for Shortcuts
Siri learns about the shortcuts available to your app through donations that your app makes to Siri. You can make donations from a user activity when the action involves a view within your app, such as the sample app, which displays a list of nearby restaurants.
The sample app enables support for Siri Shortcuts on a user activity object by setting the
eligible property to
true. The app suggests an invocation phrase, which is displayed to the user when they create a shortcut, by setting a short, memorable phrase to the
During development, the system provides developer settings to modify the display behavior of shortcuts, and force sync shortcuts to an Apple Watch from an iPhone device. Go to Settings > Developer on the iPhone device to test an app’s behavior with Siri Shortcuts.
For more information, see Donating Shortcuts.
When a user interacts with a proactive suggestion for your app, such as through Siri Shortcuts, the system restores your app to the foreground, receives data associated with its user activity, and calls
Search a chance to perform its state restoration operation through
restore, the sample app verifies the activity type of the user activity object, and passes the first tab’s view controller hierarchy to the
restoration block parameter.
The sample app validates the user activity, consumes any necessary information from the
user dictionary, and updates its UI to continue the requested activity from where the user left off.
Verify QuickType Keyboard Integration
Text fields describe the intended purpose of input data, like country name or postal code, via the
text property. If any app on the device recently donated information matching the expected text content type, that information is suggested in the QuickType keyboard as the user types in the text field.
For example, in the sample app, a user selects a pizza restaurant, and its address is suggested in Messages or a search field in Apple Maps.
To verify this behavior, select a point of interest in Apple Maps, then return to this sample app to see the donated information populated in the QuickType keyboard.