NSUserActivity

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.

When creating a user activity object, do the following:

1. Create and initialize the user activity object with an appropriate activity type. (You define the activity types your app supports.)

2. Set the title of the user activity object.

3. Configure the tasks for which the object is eligible by enabling one or more of the following properties:

   • isEligibleForHandoff

   • isEligibleForSearch

   • isEligibleForPublicIndexing

4. Configure the properties of this object that relate to the user’s current activity.

5. For user activity objects configured for search or public indexing, configure the contentAttributeSet, keywords, or webpageURL properties so that Spotlight can index the object.

6. 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.

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.

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.

For more information about using NSUserActivity objects with SiriKit, see SiriKit Programming Guide.

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.

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.