Core Spotlight

Index the content in apps that handle persistent user data, such as documents and photos, and let users deep-link to it from Spotlight and Safari search results. Add, update, and delete searchable app content.


The Core Spotlight framework helps your app participate in search by providing ways to index the content within your app (including user-generated content) and manage the on-device index. Use the APIs of the Core Spotlight framework to add, edit, and remove items from the on-device index.

Making App Content Searchable

To get started indexing app content, perform these steps:

  • Create a CSSearchable​Item​Attribute​Set object and specify properties that describe the item you want to index.

  • Create a CSSearchable​Item object to represent the item. A CSSearchable​Item object has a unique identifier that lets you refer to it later.

  • If needed, specify a domain identifier so that you can gather multiple items together and manage them as a group.

  • Associate the attribute set with the searchable item.

  • Add the searchable item to the index.

As you use Core Spotlight to make your app content searchable, you should also use NSUser​Activity to make app states and navigation points searchable and to help users return to an activity or app location when they tap on a search result. (You can also use NSUser​Activity APIs to mark an activity as public, which means that it can be shown to other users and can help encourage them to use your app.) Both Core Spotlight and NSUser​Activity use a CSSearchable​Item​Attribute​Set object to describe a searchable item and provide rich metadata that is displayed in search results. When you use both APIs, you can improve the ranking of your items in search results and prevent item duplication by specifying the same value in related​Unique​Identifier (NSUser​Activity) and unique​Identifier (CSSearchable​Item).

If your app has related content on a website, you should also mark up your website and support universal links to ensure that users can open your native app when they tap a search result supplied by your website (if your app isn’t installed, tapping the result opens Safari).




The CSCustom​Attribute​Key class defines a key that you can associate with a custom attribute for a searchable item. Item attributes provide metadata about the item that can be indexed and displayed to users in search results. Although the Core Spotlight framework provides several predefined attributes, such as title and description, you can create a CSCustom​Attribute​Key object to specify a custom attribute that makes sense in your domain.


The CSIndexExtensionRequestHandler class defines an interface you use to implement an index-maintenance app extension. An index-maintenance app extension facilitates communication between the on-device index and your app, even when your app isn’t running. For more information about using an app extension, see Using Advanced Features in App Search Programming Guide.


The CSLocalized​String class helps you localize text in searchable items. You can use a CSLocalized​String object in place of an NSString object to display localized text in search results related to your app.


A CSPerson object represents a person in the context of search results. You can create a CSPerson object when you have a display name and a contact handle of some kind, such as an email address or phone number. If you create a CSPerson object to represent a specific contact, you can use the value of the contact’s identifier property for the person object’s contact​Identifier property. Using the same value lets you avoid using names or phone numbers to look up the contact that’s associated with a person.


The CSSearchable​Index class defines an object that represents the on-device index. In your app, you can designate user activities (that is, activities that can be represented by NSUser​Activity) and app content as eligible for search. Using CSSearchable​Item and CSSearchable​Item​Attribute​Set APIs, you identify and provide information about activities and other items and then use CSSearchable​Index methods to manage the indexing of the items.


The CSSearchable​Item class defines an object that represents an item that can be indexed and made available to users when they search on their devices.


The CSSearchable​Item​Attribute​Set class defines an object that encapsulates the set of properties you want to display for a searchable item (that is, an item represented by a CSSearchable​Item object).


A search query object manages the criteria to apply when searching app content that you have previously indexed by using the Core Spotlight APIs.



The CSSearchable​Index​Delegate protocol defines methods that a delegate object or an app extension can use to handle communication from the on-device index. Apps that are long-running or that perform batch updates to the index should implement the required methods of this protocol in either a delegate object or an app extension.

Extended Types


An NSUser​Activity 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.