Framework

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.

Overview

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 CSSearchableItemAttributeSet object and specify properties that describe the item you want to index.

  • Create a CSSearchableItem object to represent the item. A CSSearchableItem 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 NSUserActivity 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 NSUserActivity 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 NSUserActivity use a CSSearchableItemAttributeSet 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 relatedUniqueIdentifier (NSUserActivity) and uniqueIdentifier (CSSearchableItem).

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

Symbols

Classes

CSCustomAttributeKey

The CSCustomAttributeKey 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 CSCustomAttributeKey object to specify a custom attribute that makes sense in your domain.

CSIndexExtensionRequestHandler

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.

CSLocalizedString

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

CSPerson

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 contactIdentifier property. Using the same value lets you avoid using names or phone numbers to look up the contact that’s associated with a person.

CSSearchableIndex

The CSSearchableIndex 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 NSUserActivity) and app content as eligible for search. Using CSSearchableItem and CSSearchableItemAttributeSet APIs, you identify and provide information about activities and other items and then use CSSearchableIndex methods to manage the indexing of the items.

CSSearchableItem

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

CSSearchableItemAttributeSet

The CSSearchableItemAttributeSet 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 CSSearchableItem object).

CSSearchQuery

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

Protocols

CSSearchableIndexDelegate

The CSSearchableIndexDelegate 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.

Structures

CSIndexErrorCSSearchQueryError

Extended Types

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

Reference

Core Spotlight EnumerationsCore Spotlight Constants