Add Features

The following sections discuss the various features that you can add to your app with the iOS SDK.

Integrate In-App Search (iOS)

YahooSearchKit provides a view controller called YSLSearchViewController that you can use to, among other things, issue search queries and display web, image, and video search results. The following section shows how you can use YSLSearchViewController to add in-app search to your application with a couple lines of code.

The YSLSearchViewController handles the entire search experience. The easiest way to integrate is to create an instance of YSLSearchViewController and present it as shown below:

YSLSearchViewController *searchViewController = [YSLSearchViewController new];
[self presentViewController:searchViewController animated:YES completion:nil];

Dismissing the Search View Controller

Adopt the YSLSearchViewControllerDelegate protocol and implement the following delegate method to be notified when the user taps the left button on the search view header. You can use this to typically dismiss the search view controller and return the user back to your app.

- (void)searchViewControllerDidTapLeftButton:(YSLSearchViewController*)searchViewController {
     // dismiss or retain search experience
}

iOS Settings

The search view controller can be initialized with custom settings by calling initWithSettings: and passing in an instance of YSLSearchViewControllerSettings. The available settings and with their default values are given below.

enableConsumptionMode

This toggles the consumption mode in search view controller. Default is YES.

Consumption mode is a popular mobile app paradigm in which the header and footer elements are automatically hidden when scrolling down a content feed (i.e., when you are “consuming” content). This allows more content to be seen on the screen. The header and footer are displayed when scrolling up or when tapping the status bar.

enableLocationService

This controls tracking user location in search results. Default is YES.

enableSearchSuggestions

This toggles showing suggestions for the search query string. Default is YES.

enableCopyrightHeader

This toggles the Copyright Header visibility in Image and Video search results for the Search-to-Link experience in the search view controller. Default is YES.

When set to NO, the Copyright Header will not be shown on top of Image and Video search results page when the Search-to-Link experience is enabled. If Search-to-Link is disabled, this flag has no effect on the search experience.

Advanced Integration

In previous sections, we initialized the search view controller by simply calling [YSLSearchViewController new]. This creates an instance of YSLSearchViewController with default settings.

You can further customize the search experience to meet the specific requirements of your app. For example, you may want to show only image search results when a user searches for “beautiful hotels in spain”. Or, if you are building a video app, you may choose to only show video search results. Perhaps you want to allow your users to share images, videos, or web links from the search results. The next section covers topics on how to customize the search experience using YSLSearchViewController.

You can customize the settings by creating an instance of YSLSearchViewControllerSettings:

YSLSearchViewControllerSettings *settings = [YSLSearchViewControllerSettings new];
settings.enableSearchSuggestions = NO;
settings.enableLocationService = NO;
...

Next, call initWithSettings: on YSLSearchViewController, passing in the settings instance you created above:

[[YSLSearchViewController alloc] initWithSettings:settings];

For example, to enable search suggestions in the search view controller, you can do the following:

YSLSearchViewControllerSettings *settings = [YSLSearchViewControllerSettings new];
settings.enableSearchSuggestions = YES;
YSLSearchViewController *searchViewController = [[YSLSearchViewController alloc] initWithSettings:settings];
[self presentViewController:searchViewController animated:YES completion:nil];

Show Search Suggestions

When you present the search view controller, it will by default show the search results for the specified query string. You can override this behavior and show search suggestions instead, which will display a list of suggestions for the same query string. The user can chose to search using the initial query string or select one of the suggested terms.

To do this, adopt the YSLSearchViewControllerDelegate protocol and implement the following delegate method:

- (YSLQueryAction)searchViewController:(YSLSearchViewController *)searchViewController actionForQueryString:(NSString *)queryString;

You can then return one of the following values for YSLQueryAction:

YSLQueryActionSearch
YSLQueryActionShowSuggestions

Select Search Result Types

By default, the search view controller displays all web, image, and video search results for a query string. However, for more control over the type of search results displayed, call the following API before presenting the search view controller:

- (void)setSearchResultTypes:(NSArray*)searchResultTypes;

For the searchResultTypes argument, you can pass an array that contains any combination of the following search result types:

YSLSearchResultTypeWeb
YSLSearchResultTypeImage
YSLSearchResultTypeVideo

The search view controller will preserve the order of the result types in your array during display. By default, the first result type in the array is selected for display.

If you don’t call this API, the search view controller will display web, image, and video search results, respectively, and will set YSLSearchResultTypeWeb as the selected result type.

In order to select a particular search result type for display, set the following property:

@property (nonatomic, copy) NSString *selectedResultType;

Example:

YSLSearchResultTypeWeb => shows web results first
YSLSearchResultTypeImage => shows image results first
YSLSearchResultTypeVideo => shows video results first

Note

This property is updated when the user selects other search result types via the UI.

Launch Custom Result Viewer

By default, clicking a link in the search results will load that URL in Safari, except for image search results which are loaded within an image gallery view. If you want to override this default experience, you can implement the following (optional) delegate methods and return NO. if you return NO, your application is responsible for loading the search result and displaying it. For example, you may choose to load a web search result in a mini browser within your app or load a video search result in your own custom video player.

- (BOOL)shouldSearchViewController:(YSLSearchViewController *)searchViewController loadWebResult:(YSLSearchWebResult *)result;
- (BOOL)shouldSearchViewController:(YSLSearchViewController *)searchViewController loadImageResult:(YSLSearchImageResult *)result;
- (BOOL)shouldSearchViewController:(YSLSearchViewController *)searchViewController loadVideoResult:(YSLSearchVideoResult *)result;

Note

If you want the Search SDK to return information on clicked search results, implement the below delegate methods and return YES.

Web Result

The YSLSearchWebResult object sent with the shouldSearchViewController:loadWebResult: delegate call has the following properties

/**
*  URL for the search result
*/
@property (nonatomic, readonly, copy) NSURL *sourceURL;

/**
*  Title for the search result. This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *title;

/**
*  Query string that was used to perform the search
*  that produced this search result
*/
@property (nonatomic, readonly, copy) NSString *queryString;

Image Result

The YSLSearchImageResult object sent with the shouldSearchViewController:loadImageResult: delegate call has the following properties

/**
*  URL for the search result
*/
@property (nonatomic, readonly, copy) NSURL *sourceURL;

/**
*  Title for the search result. This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *title;

/**
*  Query string that was used to perform the search
*  that produced this search result
*/
@property (nonatomic, readonly, copy) NSString *queryString;

/**
*  Thumbnail URL for the image search result
*/
@property (nonatomic, readonly, copy) NSURL *thumbnailURL;

Video Result

The YSLSearchVideoResult object sent with the shouldSearchViewController:loadVideoResult: delegate call has the following properties

/**
*  URL for the search result
*/
@property (nonatomic, readonly, copy) NSURL *sourceURL;

/**
*  Title for the search result. This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *title;

/**
*  Query string that was used to perform the search
*  that produced this search result
*/
@property (nonatomic, readonly, copy) NSString *queryString;

/**
*  URL for the video. This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *originalVideoURL;

/**
*  URL for streaming the video. This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *streamingVideoURL;

/**
*  Thumbnail image URL for the video
*/
@property (nonatomic, readonly, copy) NSString *thumbnailURL;

/**
*  Creation date returned as a friendly string (e.g "1 year ago").
*  This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *createdDate;

/**
*  Duration of the video returned as a string in hh:mm:ss format
*  Note: The duration value drops the hour component if it is zero
*  (e.g "01:25" should be read as 1 minute and 25 seconds. Hour component
*  is dropped because it is zero. However, minutes component is retained
*  even if it is zero - for example "00:30" is used to denote 30 seconds)
*/
@property (nonatomic, readonly, copy) NSString *duration;

/**
*  Description for the video. This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *videoDescription;