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
}
Integrate Search-to-Link (iOS)¶
About Search-to-Link¶
YahooSearchKit allows users of your application to search, select, and share links to web pages, images, and videos.
Enabling Search-to-Link¶
To enable Search-to-Link, initialize YSLSearchViewController with the enableSearchToLink option set to YES.
Example:
YSLSearchViewControllerSettings *settings = [YSLSearchViewControllerSettings new];
settings.enableSearchToLink = YES;
YSLSearchViewController *searchViewController = [[YSLSearchViewController alloc] initWithSettings:settings];
Preview Search-to-Link Results¶
Search-to-Link, which is enabled by default, lets users see a preview of a particular web page, image, or video link before it is sent. To disable this and use your own customized preview, implement the following delegate and choose to return NO.
Example:
- (BOOL)shouldSearchViewController:(YSLSearchViewController *)searchViewController previewSearchToLinkForSearchResultType:(NSString*)searchResultType;
Receive the Selected Data¶
To receive the search result data when the user clicks on a link, adopt the YSLSearchViewControllerDelegate protocol and implement the following delegate method:
- (void)searchViewController:(YSLSearchViewController *)searchViewController didSearchToLink:(YSLSearchToLinkResult *)result;
Search-to-Link Result Properties¶
The YSLSearchToLinkResult object sent with the shouldSearchViewController:didSearchToLink: 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;
/**
* Description for the Search-to-Link result. This can be empty.
*/
@property (nonatomic, readonly, copy) NSString *linkDescription;
/**
* A shortened URL for the Search-to-Link result
*/
@property (nonatomic, readonly, copy) NSURL *shortURL;
/**
* Attribution URL (for Web only). This can be empty.
*
* The attribution URL is provided for any links that you
* can receive attribution for - such as an ad. If this property is
* not empty, it is recommended that you render it in a
* webview or browser to receive attribution.
*/
@property (nonatomic, readonly, copy) NSURL *attributionURL;
/**
* Full/Original Image URL (for Image results only).
* This will be empty for web and video results.
*/
@property (nonatomic, readonly, copy) NSURL *fullURL;
/**
* Thumbnail URL (for Image and Video results only)
* This will be empty for web results.
*/
@property (nonatomic, readonly, copy) NSURL *thumbnailURL;
/**
* Address of a location or POI (for Local search results only)
*/
@property (nonatomic, readonly, copy) NSString *address;
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.
enableSearchToLink¶
This toggles the Search-to-Link experience in search view controller. Default is NO.
When set to YES, the search view controller passes the search result data back to the application when the user clicks on any link. Your application must implement the searchViewController:didSearchToLink: delegate method to be notified.
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
Show Trending Search Suggestions¶
When you present the search view controller with suggestions, it will by default show the trending search suggestions.
searchViewController.selectedTrendingCategory = YSLTrendingCategoryDefault;
To disable showing trending search suggestions, set the ‘selectedTrendingCategory’ flag to ‘YSLTrendingCategoryNone’.
searchViewController.selectedTrendingCategory = YSLTrendingCategoryNone;
You have an option to choose alternate trending category from the following options.
YSLTrendingCategoryNews
YSLTrendingCategorySports
YSLTrendingCategoryCelebrity
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 Predefined Search¶
You can launch the search view controller with a predefined query string using the following API:
searchViewController.queryString = @"flowers";
[self presentViewController:searchViewController animated:YES completion:nil];
Launch Predefined Web Search¶
You can launch Web Search using the following API:
searchViewController.queryString = @"flowers";
[searchViewController setSearchResultTypes:@[YSLSearchResultTypeWeb]];
[self presentViewController:searchViewController animated:YES completion:nil];
Launch Predefined Image Search¶
You can launch Image Search using the following API:
searchViewController.queryString = @"flowers";
[searchViewController setSearchResultTypes:@[YSLSearchResultTypeImage]];
[self presentViewController:searchViewController animated:YES completion:nil];
Launch Predefined Video Search¶
You can launch Video Search using the following API:
searchViewController.queryString = @"flowers";
[searchViewController setSearchResultTypes:@[YSLSearchResultTypeVideo]];
[self presentViewController:searchViewController animated:YES completion:nil];
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;