Class

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.

Overview

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:

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

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

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.

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.

Symbols

Creating a User Activity Object

init(activityType: String)

Initializes and returns the object using the specified type.

init()

Initializes and returns the object using the first activity type declared in the app’s information property list file.

Deprecated

Accessing Activity Information

var activityType: String

The activity type with which the user activity object was created.

var title: String?

An optional, user-visible title for this activity, such as a document name or web page title.

var requiredUserInfoKeys: Set<String>

A set of keys that represent the minimal information about the activity that should be stored for later restoration.

var userInfo: [AnyHashable : Any]?

A dictionary containing app-specific state information needed to continue an activity on another device.

func addUserInfoEntries(from: [AnyHashable : Any])

Adds the contents of the specified dictionary to the user info dictionary.

var needsSave: Bool

Indicates that the state of the activity needs to be updated.

var contentAttributeSet: CSSearchableItemAttributeSet?

A set of properties that describe the activity.

var keywords: Set<String>

A set of localized keywords that can help users find the activity in search results.

Specifying the Activity’s Eligibility

var isEligibleForHandoff: Bool

A Boolean value that indicates whether the activity can be continued on another device using Handoff.

var isEligibleForSearch: Bool

A Boolean value that indicates whether the activity should be added to the on-device index.

var isEligibleForPublicIndexing: Bool

A Boolean value that indicates whether the activity can be publicly accessed by all iOS users.

var expirationDate: Date

The date after which the activity is no longer eligible for Handoff or indexing.

Registering and Invalidating User Activities

func becomeCurrent()

Marks the activity as currently in use by the user.

func resignCurrent()

Marks this activity object as inactive without invalidating it.

func invalidate()

Invalidates an activity and marks it as no longer eligible for continuation.

Accessing the Delegate

var delegate: NSUserActivityDelegate?

The user activity object’s delegate.

Continuing Web Browsing

var webpageURL: URL?

Webpage to load in a browser to continue the activity.

Continuing Siri Interactions

var interaction: INInteraction?

The SiriKit interaction object to use when configuring your app.

Continuing an Activity With Streams

var supportsContinuationStreams: Bool

A Boolean value that determines whether the continuing app can request streams to be opened back to the originating app.

Sharing Map Item Information

var mapItem: MKMapItem!

Attaches the specified map item to a user activity object.

Relationships

Inherits From

Conforms To