NSUserActivity

Inherits From

NSObject
NSUserActivity

NSObject
NSUserActivity

Conforms To

Import Statement

Objective-C

@import Foundation;

Swift

import Foundation

Availability

Available in iOS 8.0 and later

An NSUserActivity object provides a lightweight way to capture app state so that it can be restored later. NSUserActivity supports activity restoration from Handoff, which lets users begin an activity on one device and continue it on another, and from search results. User activities include actions such as viewing app content, editing a document, viewing a web page, or watching a video. You can use the properties described in Specifying Eligibility to set whether an activity should be eligible for Handoff or different types of search (activities are eligible for Handoff by default).

Using Handoff, for example, a user who is editing a document on a Mac can continue editing that document on an iPhone. A person watching a movie on an iPad can continue watching on a Mac. In both cases, the users resume the activity at the point at which they stopped on the original device. Your apps should work to make this experience as seamless as possible.

In iOS 9 and later, an NSUserActivity object can be indexed and made available to users in search results when they perform on-device searches in Spotlight. To ensure that users get rich search results, you can provide metadata that fully describes the activity. When users select your activity from a list of search results, the system passes that activity and result to your app as it is launched, so that you can restore app state appropriately. Note that NSUserActivity is not intended to help you index arbitrary data within your app; to index app content, use the APIs of the Core Spotlight framework (to learn more, see Core Spotlight Framework Reference).

A user activity may be continued only in an app that (1) has the same developer Team ID as the activity's source app and (2) supports the activity's type. The app specifies the activity types it supports in its Info.plist under the NSUserActivityTypes key. When receiving a user activity for continuation, the system locates the appropriate app to launch by finding apps with the same Team ID as the sending app, then filtering on the incoming activity's type.

To have a Team ID, apps must be distributed through the App Store or be Developer ID–signed. Apps sharing a Team ID can selectively route activities between each other through judicious use of the activity activityType property. This lends support to related apps that are structured differently between the platforms. For example, a single Mac app can route each of its activity types to smaller, special-purpose apps on iOS.

Creating a User Activity Object


    
      
           init(activityType:)
      
      
           - initWithActivityType:

Initializes and returns a newly created NSUserActivity object with the given activity type.

Declaration

Swift

init(activityType activityType: String)

Objective-C

- (instancetype)initWithActivityType:(NSString *)activityType

Parameters


  activityType

The type of activity to be continued. The value is a developer-defined string in reverse-DNS format by convention, for example, com.myCompany.myEditor.editing.

Return Value

An NSUserActivity object.

Availability

Available in iOS 8.0 and later.

init() - init

Initializes and returns a newly created NSUserActivity object with the first activity type from the NSUserActivity key in the app’s Info.plist.

Declaration

Swift

init()

Objective-C

- (instancetype)init

Return Value

An NSUserActivity object.

Availability

Available in iOS 8.0 and later.

Specifying Eligibility

eligibleForPublicIndexing eligibleForPublicIndexing Property

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

Declaration

Swift

var eligibleForPublicIndexing: Bool

Objective-C

@property(getter=isEligibleForPublicIndexing) BOOL eligibleForPublicIndexing

Discussion

The default value of this property is NOfalse, which means that the activity contains private or sensitive information or that the activity would not be useful to other users. If you set this property to YEStrue, the activity must also have values for requiredUserInfoKeys or webpageURL.

In iOS 9.0, activities marked as eligibleForPublicIndexing are added to the private, on-device index. Identifying an activity as public confers an advantage when you also add web markup to the content on your related website. Specifically, when users engage with your app’s public activities in search results, it indicates to Apple that public information on your website is popular, which can help increase your ranking and potentially lead to expanded indexing of your website’s content.

Availability

Available in iOS 9.0 and later.
eligibleForSearch eligibleForSearch Property

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

Declaration

Swift

var eligibleForSearch: Bool

Objective-C

@property(getter=isEligibleForSearch) BOOL eligibleForSearch

Discussion

The default value of this property is NOfalse.

Availability

Available in iOS 9.0 and later.
eligibleForHandoff eligibleForHandoff Property

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

Declaration

Swift

var eligibleForHandoff: Bool

Objective-C

@property(getter=isEligibleForHandoff) BOOL eligibleForHandoff

Discussion

The default value of this property isYEStrue.

Availability

Available in iOS 9.0 and later.
expirationDate expirationDate Property

The date after which the activity is no longer eligible to be indexed or handed off.

Declaration

Swift

@NSCopying var expirationDate: NSDate

Objective-C

@property(copy) NSDate *expirationDate

Discussion

If you don’t set the expirationDate property appropriately, the system automatically expires the activity after a period of time.

Availability

Available in iOS 9.0 and later.

Continuing an Activity With Streams

supportsContinuationStreams supportsContinuationStreams Property

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

Declaration

Swift

var supportsContinuationStreams: Bool

Objective-C

@property BOOL supportsContinuationStreams

Discussion

If the value of this property is YEStrue, the continuing app can connect back to the originating app for more information using streams. This value is set to NOfalse by default. It can dynamically be set to YEStrue to selectively support continuation streams based on the state of the user activity.

Availability

Available in iOS 8.0 and later.


    
      
           getContinuationStreamsWithCompletionHandler(_:)
      
      
           - getContinuationStreamsWithCompletionHandler:

Requests streams back to the originating app.

Declaration

Swift

func getContinuationStreamsWithCompletionHandler(_ completionHandler: (NSInputStream?, NSOutputStream?, NSError?) -> Void)

Objective-C

- (void)getContinuationStreamsWithCompletionHandler:(void (^)(NSInputStream *inputStream, NSOutputStream *outputStream, NSError *error))completionHandler

Parameters


  completionHandler

The completion handler block that returns streams.

The block takes three arguments:

`inputStream`	The stream from which the continuing app can read data written by the originating app.
`outputStream`	The stream to which the continuing app writes data to be read by the originating app.


  error

If successful, nil; if not successful, an NSError object that encapsulates the reason why the streams could not be created.

Discussion

When an app is launched for a continuation event, it can request streams back to the originating app. Streams can be successfully retrieved only from the NSUserActivity object in the NSApplication or UIApplication delegate that is called for a continuation event. The streams are provided by the completion handler in an unopened state, and the delegate should open them immediately to start communicating with the continuing side.

Continuation streams are an optional feature of Handoff, and most user activities do not need them for successful continuation. When streams are needed, a simple request from the continuing app accompanied by a response from the originating app is enough for most continuation events.

Availability

Available in iOS 8.0 and later.

Maintaining Activity State

userInfo userInfo Property

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

Declaration

Swift

var userInfo: [NSObject : AnyObject]?

Objective-C

@property(copy) NSDictionary *userInfo

Discussion

Each key and value must be of the following types: NSArray, NSData, NSDate, NSDictionary, NSNull, NSNumber, NSSet, NSString, or NSURL. The system may translate file scheme URLs that refer to iCloud documents to valid file URLs on a continuing device.

Availability

Available in iOS 8.0 and later.
addUserInfoEntriesFromDictionary(_:) - addUserInfoEntriesFromDictionary:

Adds to the userInfo dictionary the entries from the given dictionary.

Declaration

Swift

func addUserInfoEntriesFromDictionary(_ otherDictionary: [NSObject : AnyObject])

Objective-C

- (void)addUserInfoEntriesFromDictionary:(NSDictionary *)otherDictionary

Parameters

otherDictionary

The dictionary containing entries to be added.

Discussion

Transfer as small a payload as possible in the userInfo dictionary. The more payload data you deliver, the longer it takes the activity to resume.

Availability

Available in iOS 8.0 and later.
becomeCurrent() - becomeCurrent

Marks the activity as the activity currently in use by the user.

Declaration

Swift

func becomeCurrent()

Objective-C

- (void)becomeCurrent

Discussion

A typical example of a current user activity is the activity associated with the foremost active window. A newly created user activity is eligible for continuation on another device after the first time it becomes current.

Availability

Available in iOS 8.0 and later.
resignCurrent() - resignCurrent

Tells the activity that it should no longer be the activity currently in use by the user.

Declaration

Swift

func resignCurrent()

Objective-C

- (void)resignCurrent

Discussion

If the activity is the current activity, calling this method tells it to stop being current and sets the current activity to nil . A noncurrent activity is no longer eligible for continuation on another device.

Availability

Available in iOS 9.0 and later.
delegate delegate Property

The user activity object’s delegate.

Declaration

Swift

weak var delegate: NSUserActivityDelegate?

Objective-C

@property(weak) id< NSUserActivityDelegate > delegate

Discussion

The user activity delegate is informed when the activity is being saved or continued (see NSUserActivityDelegate).

Availability

Available in iOS 8.0 and later.
needsSave needsSave Property

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

Declaration

Swift

var needsSave: Bool

Objective-C

@property(assign) BOOL needsSave

Discussion

If YEStrue, the delegate for this user activity receives a userActivityWillSave: callback before the activity is sent for continuation on another device.

Availability

Available in iOS 8.0 and later.
invalidate() - invalidate

Invalidates an activity when it's no longer eligible for continuation.

Declaration

Swift

func invalidate()

Objective-C

- (void)invalidate

Discussion

The app invokes this method when the user stops engaging in the activity, such as when the window associated with the activity is closed. An invalid activity cannot become current.

Availability

Available in iOS 8.0 and later.

Identifying the Activity

activityType activityType Property

The activity type with which the user activity object was created. (read-only)

Declaration

Swift

var activityType: String { get }

Objective-C

@property(readonly, copy) NSString *activityType

Discussion

This property is read-only because the activity type cannot be changed after the user activity object is created. It’s a good idea to use a reverse-DNS string for the value of this property so that it uniquely identifies the activity type.

Availability

Available in iOS 8.0 and later.
title title Property

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

Declaration

Swift

var title: String?

Objective-C

@property(copy) NSString *title

Discussion

An activity’s title can be used in indexing as well as for display in search results.

Availability

Available in iOS 8.0 and later.
contentAttributeSet contentAttributeSet Property

A set of properties that describe the activity.

Declaration

Swift

@NSCopying var contentAttributeSet: CSSearchableItemAttributeSet?

Objective-C

@property(copy) CSSearchableItemAttributeSet *contentAttributeSet

Discussion

A CSSearchableItemAttributeSet object encapsulates the set of properties you want to display for a searchable activity.

Import Statement

Objective-C

@import CoreSpotlight;

Swift

import CoreSpotlight

Availability

Available in iOS 9.0 and later.
keywords keywords Property

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

Declaration

Swift

var keywords: Set<String>

Objective-C

@property(copy) NSSet <NSString *> *keywords

Discussion

The default value of this property is nil. The system indexes the keywords you provide.

Availability

Available in iOS 9.0 and later.
requiredUserInfoKeys requiredUserInfoKeys Property

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

Declaration

Swift

var requiredUserInfoKeys: Set<String>

Objective-C

@property(copy) NSSet <NSString *> *requiredUserInfoKeys

Discussion

The keys come from the userInfo property.

Availability

Available in iOS 9.0 and later.

Continuing Web Browsing

webpageURL webpageURL Property

Webpage to load in a browser to continue the activity.

Declaration

Swift

@NSCopying var webpageURL: NSURL?

Objective-C

@property(copy) NSURL *webpageURL

Discussion

When no suitable app is installed on a resuming device and the webpageURL property is set, the specified webpage is loaded and the user activity is continued in a web browser.

If your activity's content can be restored on the web or you support Safari universal links, be sure to set this property so that the system can resume the activity in Safari or your app. After setting the webpageURL property on an activity for which eligibleForSearch is YEStrue, also set the requiredUserInfoKeys property, using the keys of the userInfo dictionary that must be stored. If you don’t also set the requiredUserInfoKeys property, the userInfo dictionary will be empty when the activity is restored.

If eligibleForSearch is YEStrue for this activity and you’re using both NSUserActivity and web markup to index the same item, set webpageURL to the relevant URL on your website to avoid showing duplicate results in Spotlight. The NSUserActivity API does not perform any modifications to the URL that you specify. URL components, such as the query string and the fragment identifier, are used for matching the item against pages that are indexed by Applebot.

Note

The scheme of the webpageURL must be http or https. Any other scheme throws an exception.

Availability

Available in iOS 8.0 and later.