Contents

NSUserActivity

A representation of the state of your app at a moment in time.

Declaration

class NSUserActivity

Mentioned in

Overview

An NSUserActivity object provides a lightweight way to capture the state of your app and put it to use later. Create this object to capture information about what a person 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 these objects to improve search results for people. To allow people to continue an activity on another device, see Implementing Handoff in Your App.

Siri

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.

In iOS 15 and later, a person can share content they’re viewing by asking Siri to “share this”. Apps built with Mac Catalyst provide the same capability with an NSSharingServicePickerToolbarItem in the toolbar. You can use activityItemsConfiguration or activityItemsConfigurationSource to provide shareable content. In iOS, if both of those properties are nil, Siri uses the webpageURL property of your app’s current user activity as a fallback value.

Quick Note

Quick Note on macOS and iOS can link to any app content represented as an NSUserActivity. To appear as a link, the content must be the app’s current activity, and provide at least one of the following identifiers:

webpageURL

An https: URL, ideally in a canonical form that’s consistent every time a person visits the same content.

persistentIdentifier

A string that uniquely identifies the content in this domain. The identifier should identify the same content across devices.

targetContentIdentifier

A string that uniquely identifies the content in this domain, but also allows disambiguating between multiple scenes of an app. The identifier should identify the same content across devices.

To work well with Quick Note, content must adhere to the following guidelines:

  • The activity title should be clear and concise. This text describes the content of the link, like “Photo taken on July 27, 2020” or “Conversation with Maria”. Use nouns for activity titles.

  • Keep the app’s current activity up to date, using becomeCurrent() and resignCurrent().

  • Linkable identifiers (listed above) must be stable and consistent for the same content. When you link from a note to a document in an app, and later revisit that document, the system shows an indicator linking back to the note. The system compares identifiers to check that the document is the same as the original source of the link.

  • Maintain support for activities provided by your app, and support navigating to linked content indefinitely. Links added to notes are important to people, who may feel that a broken link indicates data loss.

  • Gracefully handle attempts to navigate to an activity that points to content that doesn’t exist. For example, you can redirect to the new location of moved content, or show an error message. This situation may happen with shared notes, when a person links to content that exists only on another person’s device.

Search results

If your NSUserActivity objects contain information that a person 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 a person viewed information about a particular restaurant in your app, you’d 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 people. To contribute a URL, put the URL in the webpageURL property of your activity object and set the isEligibleForPublicIndexing property to true.

Employ user activity objects to record user-initiated activities, not as a general-purpose indexing mechanism of your app’s data. To index all of your app’s content, and not just the content touched by people, use the APIs of the Core Spotlight framework.

Topics

Creating a user activity object

Accessing activity information

Specifying the activity’s eligibility

Registering and invalidating user activities

Deleting saved user activities

Accessing the delegate

Working with continuation streams

Continuing web browsing

Donating to Siri Shortcuts

Continuing Siri interactions

Retrieving NFC tag data

Processing barcodes

Sharing map item information

Working with media

Managing type-safe access to user info

Working with ClassKit

Identifying activity types

Reporting errors

Instance Properties

Instance Methods

Default Implementations

See Also

Host App Interaction