Declaration

Overview

An NSUserActivity object provides a lightweight way to capture the state of your app and put it to use later. You create user activity objects and use them to capture information about what the user was doing, such as viewing app content, editing a document, viewing a web page, or watching a video. When the system launches your app and an activity object is available, your app can use the information in that object to restore itself to an appropriate state. Spotlight also uses your user activity objects to improve search results for the user.

You create NSUserActivity objects at key moments and register them with the system. For example, you might create a user activity object when the user opens a web page, when your app moves to the background, or when the user performs some other significant task in your app. User activity objects are not intended as a way to track every task in your app, so you should not use them for small edits or other minor changes. Instead, use them for significant checkpoints that the user might want to continue later or on another device. You can also use them to provide better Spotlight search results.

Call the becomeCurrent() method to register the user activity object with the system.

When you create an NSUserActivity object, you specify a string that identifies the type of the activity. Activity type strings are typically in reverse-DNS format. For example, when the user opens a web page, you might specify an activity string such as com.myCompany.myApp.OpenWebPage. You must declare the activity types that your app supports by including the NSUserActivityTypes key in its Info.plist file. The system uses the information in that key to determine whether your app is capable of handling a given user activity object.

The system associates user activity objects with the ID of the developer that created them. When continuing an activity, the system looks for an app that supports the given activity type and has the same developer Team ID as the activity’s source app. Tying activity objects to your developer Team ID ensures that the activities you create cannot be intercepted by a competitor’s app. Relying on the Team ID also means that your apps must be distributed through the App Store or be signed with your developer ID.

Supporting Handoff

Handoff is a technology that lets users begin an activity on one device and continue it on another. For Handoff, user activity objects convey information about what the user was doing in one context so that it can be used in another context. For example, a user who is watching a video on an iPad can start continue watching the video from the same point on their Mac. In that example, the user activity object contains information about the video that the user was watching and the place where they stopped watching it on the iPad.

To support Handoff, configure your user activity objects with the data needed to continue the activity and set the isEligibleForHandoff property to true.

Supporting SiriKit

If SiriKit needs to launch your app for any reason, it creates a user activity object and assigns an appropriate INInteraction object to its interaction property. Your app can use the interaction information to configure itself and display information related to the interaction started by SiriKit. You can also provide SiriKit with a custom user activity object containing additional data that you want passed to your app.

Supporting Improved Search Results

If your NSUserActivity objects contain information that the user might want to search for later, set the isEligibleForSearch property to true. When you enable search, Spotlight indexes your user activity objects and considers them during subsequent on-device searches. For example, if the user viewed information about a particular restaurant in your app, you would enable search for the corresponding user activity object. Subsequent searches for restaurants using Spotlight could then include the results obtained from your user activity object.

In addition to on-device searches, you can contribute URLs accessed by your app with the global Spotlight search engine. Sharing a URL helps Spotlight improve its own search results for other users. To contribute a URL, put the URL in the webpageURL property of your activity object and set the isEligibleForPublicIndexing property to true.

Important

Your app must maintain a strong reference to any activity objects that you use for search results.

User activity objects are intended only for recording user-initiated activities. They are not intended as a general-purpose indexing mechanism for your app’s data. To index all of your app’s content, and not just the content touched by the user, use the APIs of the Core Spotlight framework. For more information, see Core Spotlight.

The interface through which a user activity instance notifies its delegate of updates.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.