iOS 9 Learning Series: Search API

[[146026]]

introduce

At the WWDC 2015 conference, Apple officially announced iOS 9. In addition to many new features and enhancements, this upgrade also gave developers an opportunity to make the content in their apps discoverable and usable through Spotlight search. The new APIs available in iOS 9 allow you to index the content or interface state in your app and make it available to users through Spotlight. The three major components of these new search APIs are:

• NSUserActivity class, which is designed for visible app content

• Core Spotlight framework, designed for any APP content

• Web markup, designed for this type of APP, means that the content of the APP is mirrored on a certain website

In this tutorial, I'll show you how you can use the NSUserActivity class and the Core Spotlight framework in your apps.

Preparation

This tutorial requires you to be running Xcode7 and OSX 10.10 or later. To follow along, you’ll also need to download the starter project from GitHub.

1. Using NSUserActivity

At the beginning of this tutorial, I will show you how to index the content of an app through the NSUserActivity class. This API is also the one used in Handoff, a feature introduced in iOS 8 last year, which is used to save and restore the current state of an app.

If you haven’t used NSUserActivity before, I recommend reading my tutorial that covers the basics of Handoff and NSUserActivity before starting this one.

Before you start writing code, open the starter project and run the app on the iOS simulator or a test machine. At this stage, you will see that the app simply displays a list of 4 TV shows and a detailed page for each show.

First, open the project and go to the DetailViewController.swift file. Replace the contents of the configureView method in the DetailViewController class with the following:

 func configureView() {
 // Update the user interface for the detail item.  
 if self.nameLabel != nil && self.detailItem != nil {
        self.nameLabel.text = detailItem.name
        self.genreLabel.text = detailItem.genre 
           
        let dateFormatter = NSDateFormatter()
        dateFormatter.timeStyle = .ShortStyle
        self.timeLabel.text = dateFormatter.stringFromDate(detailItem.time) 
           
        let activity = NSUserActivity(activityType: "com.tutsplus.iOS-9-Search.displayShow" )
        activity.userInfo = [ "name" : detailItem.name, "genre" : detailItem.genre, "time" : detailItem.time]
        activity.title = detailItem.name
 var keywords = detailItem.name.componentsSeparatedByString( " " )
        keywords.append(detailItem.genre)
        activity.keywords = Set(keywords)
        activity.eligibleForHandoff = false  
        activity.eligibleForSearch = true  
 //activity.eligibleForPublicIndexing = true  
 //activity.expirationDate = NSDate()   
   
        activity.becomeCurrent()
 }
 }

In the view controller, the code for configuring the label remains unchanged. Let’s analyze the user activity code step by step:

1. Create a new NSUserActivity object using the unique identifier com.tutsplus.iOS-9-Search.displayShow. The project has been configured to ensure that this identifier is not changed when used.

2. Then assign a userInfo dictionary to this user activity. It will be used later to restore the state of the application.

3. Assign a string value to the activity's title attribute. This is what will appear in Spotlight search results.

4. To ensure that the searchable content is not limited to the title of the application, you also need to provide a list of keywords. In the above code snippet, the keyword list includes the name of each program and its genre.

5. Next, you assign some properties to the NSUserActivity object to tell the operating system what you want the user activity to do. In this tutorial, we're just looking at the search component API so we'll disable Handoff and enable search.

6. Finally, the user activity's becomeCurrent method is called, at which point it is automatically added to the device's search results index.

In the implementation code above, you may have noticed two commented statements. Although we will not use these properties in this tutorial, it is important to understand what each property is used for.

1. In the implementation above, each user activity and search result for a show is created only if the app has been opened. When you make your user activities eligibleForPublicIndexing, Apple begins observing the use and interactions of this particular activity from the user's search results. If this search result is used by many users, Apple promotes the user activity to its cloud index. Once the user activity is in the cloud index, it can be searched by anyone who has installed your app, regardless of whether they have opened the content. This property can only be set to true if and only if the activities are available to all users of your app.

2. A user activity can have an optional property called expirationDate. When this property is set, your user activity will only be shown in search results before the set expiration date.

Now that you know how to create an NSUserActivity that can display search results in Spotlight, it’s time to experiment. Build and run your app, then open some programs in your app. Once you’ve done that, return to the home page (press Command-Shift-H in the iOS Simulator) and swipe down or swipe to the far left of the screen to pull up the search box view.

Enter the title of a program you have already opened in the search box, and you will see it displayed in the search results, as shown below.

Alternatively, enter a category for a show you've already opened. Since you've assigned keyword information to the user activity, this will also cause the show to be listed in the search results list.

Your app's content is correctly indexed by the OS and the results appear in Spotlight. However, when you tap a search result, your app doesn't take the user to the search result they were looking for, but simply launches the app.

#p#

Fortunately, with Handoff, you can take advantage of the NSUserActivity class to restore the correct state in your app. To make this possible we need to implement two methods.

Implement the application(_:continueUserActivity:restorationHandler:) method in the AppDelegate class as follows:

 func application(application: UIApplication, continueUserActivity userActivity: NSUserActivity, restorationHandler: ([AnyObject]?) -> Void) -> Bool {
    let splitController = self.window?.rootViewController as! UISplitViewController
    let navigationController = splitController.viewControllers.first as! UINavigationController
    navigationController.topViewController?.restoreUserActivityState(userActivity)
 return   true  
 }

 override func restoreUserActivityState(activity: NSUserActivity) {
 if let name = activity.userInfo?[ "name" ] as? String,
        let genre = activity.userInfo?[ "genre" ] as? String,
        let time = activity.userInfo?[ "time" ] as? NSDate {
        let show = Show(name: name, genre: genre, time: time)
        self.showToRestore = show 
           
        self.performSegueWithIdentifier( "showDetail" , sender: self)
 }
 else {
        let alert = UIAlertController(title: "Error" , message: "Error retrieving information from userInfo:\n\(activity.userInfo)" , preferredStyle: .Alert)
        alert.addAction(UIAlertAction(title: "Dismiss" , style: .Cancel, handler: nil)) 
           
        self.presentViewController(alert, animated: true , completion: nil)
 }
 }

At the time of writing this article, the latest version of Xcode7 (Beta3) has a problem where the userInfo property of a fixed user activity becomes null. That's why I handle errors and show a warning with the userInfo information (returned by the operating system).

Build and run your app again and search for a show. When you tap a show in the search results, the app will take you directly to the details view controller and display the current information about the show you selected.

2. Use the Core Spotlight framework

Another API that makes your content searchable to users in iOS 9 is the Core Spotlight framework. This framework has a database-like design and can provide you with more information about the content you want to be searchable.

Before you can use the Core Spotlight framework, we need to link the project to the framework. In the Project Navigator, select the project and open the top Build Phases section. Next, expand the Link Binary With Libraries section and click the plus button. In the pop-up menu, search for CoreSpotlight and link your project to the framework. Repeat these steps to link the MobileCoreServices framework.

Next, to ensure that the search results provided by our app are indeed from Core Spotlight, delete your app on your test machine or simulator and comment out the following statement in the DetailViewController class:

 activity.becomeCurrent()

Finally, open MasterViewController.swift and add the following statement just before the Show struct definition:

 import CoreSpotlight
 import MobileCoreServices

Next, add the following code to the viewDidLoad method of the MasterViewController class:

 var searchableItems: [CSSearchableItem] = []
 for show in objects {
    let attributeSet = CSSearchableItemAttributeSet(itemContentType: kUTTypeItem as String) 
       
    attributeSet.title = show.name 
       
    let dateFormatter = NSDateFormatter()
    dateFormatter.timeStyle = .ShortStyle 
       
    attributeSet.contentDescription = show.genre + "\n" + dateFormatter.stringFromDate(show.time) 
       
 var keywords = show.name.componentsSeparatedByString( " " )
    keywords.append(show.genre)
    attributeSet.keywords = keywords 
       
    let item = CSSearchableItem(uniqueIdentifier: show.name, domainIdentifier: "tv-shows" , attributeSet: attributeSet)
    searchableItems.append(item)
 } 
   
 CSSearchableIndex.defaultSearchableIndex().indexSearchableItems(searchableItems) { (error) -> Void in  
 if error != nil {
        print(error?.localizedDescription)
 }
 else {
 // Items were indexed successfully  
 }
 }

Before verifying this code, let's go through each step in the for loop.

1. You create a CSSearchableItemAttributeSet object, passing in a content type for the item. For example, if your search result links to a photo, you would pass in the kUTTypeImage constant.

2. Assign the title property of the attribute set the name of the program. Just like NSUserActivity, this title is what will appear at the top of the search results list.

3. Next, create a descriptive string and assign it to the contentDescription property of the searchable attribute set. This string will appear below the title of the search result in Spotlight.

4. Just like we did in NSUserActivity, create an array of keywords from the search results.

5. Finally, create a CSSearchableItem with a unique item identifier, a unique domain identifier (used to group CSSearchableItem items), and an attribute set. Unlike NSUserActivity, which returns the user activity from the search results, all the unique identifier information set for the CSSearchableItem is the only information you can get from the operating system when your search result is selected by the user. You need to use these identifiers to restore your application back to the correct state.

Once you’ve created a CSSearchableItem for each TV show, you index them using the indexSearchableItems(_:completionHandler:) method and the default CSSearchableIndex object.

Build and run your app, and all your shows will be indexed by Spotlight. Go to the search page and search for one of the shows.

Core Spotlight search results are handled by the same method as NSUserActivity, but the process is slightly different. When a CSSearchableItem is selected in the search results, the system creates an NSUserActivity object for you that contains the selected item’s unique identifier information.

In your app delegate’s application(_:continueUserActivity:restorationHandler:) method, you can use the following implementation to get the information you want from the Core Spotlight search results:

 if userActivity.activityType == CSSearchableItemActionType {
 if let identifier = userActivity.userInfo?[CSSearchableItemActivityIdentifier] as? String { 
           
 // Use identifier to display the correct content for this search result   
           
 return   true  
 }
 }

A good practice for indexing app content using the Core Spotlight framework is to remove items when they are no longer needed. The CSSearchableIndex class provides three methods to remove searchable items:

• deleteAllSearchableItemsWithCompletionHandler(:)

• deleteSearchableItemsWithDomainIdentifiers(:completionHandler:)

• deleteSearchableItemsWithIdentifiers(_:completionHandler:)

#p#

As an example, add the following code to the viewDidLoad method of the MasterViewController class:

 CSSearchableIndex.defaultSearchableIndex().deleteSearchableItemsWithDomainIdentifiers([ "tv-shows" ]) { (error) -> Void in  
 if error != nil {
        print(error?.localizedDescription)
 }
 else {
 // Items were deleted successfully  
 }
 }

Build and run your app again. When you try to search for any show, no results will be returned because they have been deleted from the index.

3. Combine NSUserActivity and Core Spotlight

Another new feature added to the NSUserActivity class in iOS 9 is the contentAttributeSet property. This property allows you to assign a CSSearchableItemAttributeSet, just like the one you created earlier. This attribute set allows search results for NSUserActivity objects to display the same amount of detailed information as Core Spotlight search results.

Start by adding the following imports to the top of DetailViewController.swift:

 import CoreSpotlight
 import MobileCoreServices

Next, update the configureView method of the DetailViewController class with the following implementation:

 func configureView() {
 // Update the user interface for the detail item.  
 if self.nameLabel != nil && self.detailItem != nil {
        self.nameLabel.text = detailItem.name
        self.genreLabel.text = detailItem.genre 
           
        let dateFormatter = NSDateFormatter()
        dateFormatter.timeStyle = .ShortStyle
        self.timeLabel.text = dateFormatter.stringFromDate(detailItem.time) 
           
        let activity = NSUserActivity(activityType: "com.tutsplus.iOS-9-Search.displayShow" )
        activity.userInfo = [ "name" : detailItem.name, "genre" : detailItem.genre, "time" : detailItem.time]
        activity.title = detailItem.name
 var keywords = detailItem.name.componentsSeparatedByString( " " )
        keywords.append(detailItem.genre)
        activity.keywords = Set(keywords)
        activity.eligibleForHandoff = false  
        activity.eligibleForSearch = true  
 //activity.eligibleForPublicIndexing = true  
 //activity.expirationDate = NSDate()   
           
        let attributeSet = CSSearchableItemAttributeSet(itemContentType: kUTTypeItem as String)
        attributeSet.title = detailItem.name
        attributeSet.contentDescription = detailItem.genre + "\n" + dateFormatter.stringFromDate(detailItem.time) 
   
        activity.becomeCurrent()
 }
 }

Build and run the app one last time, then open some shows. When you search for a show, you’ll see your results, along with the NSUserActivity created, with the same level of detail as Core Spotlight search results.

Summarize

In this tutorial, you learned how to use the NSUserActivity class and the Core Spotlight framework to make content in your app indexable by iOS Spotlight. I also showed you how to use these two APIs to index content in your app and how to restore your app’s state when a search result is selected by the user.

The new search APIs introduced in iOS 9 are easy to use and can make the content in your app easier to discover and engage with for users. As always, if you have any comments or questions, leave them in the comments box below.