How to add Spotlight support to your iOS app

A Swift tutorial that will make your app available in Spotlight search

The #1 challenge for any individual or startup that owns a mobile app is how to increase the user retention rate. You can attract users to download the app, but what happens after the first usage?

Some users will delete your app, and some will find it useful and keep it. But, that doesn’t always mean that they will use it if they have it installed on their phones. Usually, the app can end up hidden in some folder or in a sea of hundreds of apps installed.

That’s why we need to think of ways to remind users that our app is present.

Apple offers us many iOS features that can boost our apps visibility even when the user is not using it. For example, features like Spotlight, Today Widget, iMessage, Push Notifications, Siri and so on...

In this tutorial, I will cover how to utilize the Spotlight feature properly for your iOS app. I have recently implemented this feature in my latest iOS app called 1BET so all the screenshots that you will see will be from there.

Spotlight

Spotlight is a super-powerful search feature in iOS that searches through the contents of your installed apps that support it. It is similar to the search that you experience on Safari. It also syncs with Siri and provides you with a Top Hits section. You can locate Spotlight by swiping down from the home menu.

I will cover the two most important things to know about Spotlight:

Enabling your content to be searchable on Spotlight;
Intercepting the pressed item back to your iOS app;

#1 Creating Searchable Content

If we want our app content to appear in Spotlight, we need to use the CoreSpotlight framework. For creating searchable content we will need to be familiar with:

CSSearchableItemAttributeSet - specifies the properties that you want to appear in Spotlight (i.e. title, contentDescription, thumbnail).
CSSearchableItem - this class represents the search item. We can assign a unique identifier for referring the object, a domain to manage the items in groups and attributeSet where we pass the CSSearchableItemAttributeSet that we have created for this object.
CSSearchableIndex - a class that is responsible for indexing the content on Spotlight. It requires an array of CSSearchableItem.

Now, let's see these an example with these three classes together in action. 👇

This is how I handle the Spotlight support in 1BET…

The CoreSpotlight framework has its own rules what it would show, and we must follow them. CSSearchableItem is the data model that we need to utilize in order to get the Spotlight working. As you can see, I am iterating over my data model, and creating CSSearchableItem objects with the properties I need. After that, just add all the newly created items into an array and pass it to CSSearchableIndex.

At this point, you need to start seeing results inside Spotlight when you start searching. That's it! 😉

NOTE: There are of course more properties than what you can see above. You can find that in the official Apple documentation.

**When are domains useful?**The CSSearchableItem domain attribute can be quite useful. If you had any confusion why we need domains, I will explain one situation now… In my case, I am having 2 different domains matches and news. The matches domain is filled in with match betting tips and news is filled in with the latest sports articles.

Now, I am showing news only in some specific cases. That means sometimes I don't want them to appear in Spotlight. And if you have already added them to the index, they will stay there. Which means we need to find a way to delete all the entries from that domain (group) only. 👇

With CSSearchableIndex we can easily delete all the searchable items for a specific domain. You can also add multiple domains at the same time.

#2 Intercept the pressed item

This is a situation where the user finds some of your search results on Spotlight interesting and wants to see more info. The user clicks on the item and is automatically redirected to your app. But, if we don't intercept the item properly the user will only end up on the initial screen of your app, instead of being redirected to the specific content.

http://apple.co/2CrlXDf

This is a flow of how a user opens Spotlight, makes a search and by clicking on one of the items it gets redirected to the Match Overview screen.

**App Delegate**First, go to AppDelegate.swift and add the below snippet. This method will trigger restoreUserActivityState() inside your root view controller. You can also notice that we are passing the NSUserActivity object which contains the data of our pressed item. 👇

NOTE: The location of my root view controller is like shown in the example. You will have to change that with your own logic.

**UIViewController**The last step is to open the view controller that you have cast in the AppDelegate method and override restoreUserActivityState() there. 👇

If you have followed this tutorial from the start, you will notice that we are passing a unique identifier to every CSSearchableItem that we create. The restoreUserActivityState will return us this identifier which will enable us to find the suitable object and also present the suitable view controller where the user should be navigated to.

That's it from this tutorial, I hope that it helped you learn how to add the Spotlight support for your iOS app. I also hope that this feature will provide a positive boost inside your analytics software. 📈

I would appreciate if you 👏 or share this story so others can find it and learn from it. Cheers!

Check out my latest project:

‎VIP Sports Bet Tips & Scores on the App Store_This app is only available on the App Store for iOS devices. Increase your profits by following our professional BET…_apple.co