By Algolia.
InstantSearch family: InstantSearch iOS | InstantSearch Android | React InstantSearch | InstantSearch.js | Angular InstantSearch | Vue InstantSearch.
InstantSearch iOS is a framework providing components and helpers to help you build the best instant-search experience on iOS with Algolia. It is built on top of Algolia's Swift API Client library to provide you a high-level solution to quickly build various search interfaces.
Structure
InstantSearch iOS consists of three products
- InstantSearch Insights – library that allows developers to capture search-related events
- InstantSearch Core – the business logic modules of InstantSearch without provided UIKit controllers
- InstantSearch – the complete InstantSearch toolset including UIKit and SwiftUI components
Demo
You can see InstantSearch iOS in action in our Examples repository, in which we published search experiences built with InstantSearch and written in Swift:
Installation
Swift Package Manager
The Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. Since the release of Swift 5 and Xcode 11, SPM is compatible with the iOS, macOS and tvOS build systems for creating apps.
To use SwiftPM, you should use Xcode 11 to open your project. Click File -> Swift Packages -> Add Package Dependency, enter InstantSearch repo's URL. Next, select the products you consider to use in your project from the provided list.
If you're a framework author and use InstantSearch as a dependency, update your Package.swift file:
let package = Package(
// 7.11.0 ..< 8.0.0
dependencies: [
.package(url: "https://github.com/algolia/instantsearch-ios", from: "7.11.0")
],
// ...
)
CocoaPods
CocoaPods is a dependency manager for Cocoa projects.
To install InstantSearch, simply add the following line to your Podfile:
pod 'InstantSearch', '~> 7.11'
# pod 'InstantSearch/Insights' for access to Insights library only
# pod 'InstantSearch/Core' for access business logic without UIKit components
# pod 'InstantSearch/SwiftUI' for access to SwiftUI components
Then, run the following command:
$ pod update
Carthage
Carthage is a simple, decentralized dependency manager for Cocoa.
- To install InstantSearch, simply add the following line to your Cartfile:
github "algolia/instantsearch-ios" ~> 7.11
- Launch the following commands from the project directory
carthage update
./Carthage/Checkouts/instant-search-ios/carthage-prebuild
carthage build
NOTE: At this time, Carthage does not provide a way to build only specific repository subcomponents (or equivalent of CocoaPods's subspecs). All components and their dependencies will be built with the above command. However, you don't need to copy frameworks you aren't using into your project. For instance, if you aren't using UI components from
InstantSearch, feel free to delete that framework from the Carthage Build directory aftercarthage updatecompletes keeping onlyInstantSearchCore. If you only need event-tracking functionalities, delete all butInstantSearchInsightsframework.
If this is your first time using Carthage in the project, you'll need to go through some additional steps as explained over at Carthage.
Documentation
You can start with the Getting Started Guide.
Learn more about instantSearch iOS in the dedicated documentation website.
Basic Usage
In your ViewController.swift:
import InstantSearch
struct BestBuyItem: Codable {
let name: String
}
struct BestBuyTableViewCellConfigurator: TableViewCellConfigurable {
let model: BestBuyItem
init(model: BestBuyItem, indexPath: IndexPath) {
self.model = model
}
func configure(_ cell: UITableViewCell) {
cell.textLabel?.text = model.name
}
}
typealias BestBuyHitsViewController = HitsTableViewController<BestBuyTableViewCellConfigurator>
class ViewController: UIViewController {
let searcher = SingleIndexSearcher(appID: "latency",
apiKey: "1f6fd3a6fb973cb08419fe7d288fa4db",
indexName: "bestbuy")
lazy var searchController: UISearchController = .init(searchResultsController: hitsTableViewController)
lazy var searchConnector: SingleIndexSearchConnector<BestBuyItem> = .init(searcher: searcher,
searchController: searchController,
hitsController: hitsTableViewController)
let hitsTableViewController: BestBuyHitsViewController = .init()
let statsInteractor: StatsInteractor = .init()
override func viewDidLoad() {
super.viewDidLoad()
searchConnector.connect()
statsInteractor.connectSearcher(searcher)
statsInteractor.connectController(self)
searcher.search()
setupUI()
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
searchController.searchBar.becomeFirstResponder()
}
func setupUI() {
view.backgroundColor = .white
navigationItem.searchController = searchController
searchController.hidesNavigationBarDuringPresentation = false
searchController.showsSearchResultsController = true
searchController.automaticallyShowsCancelButton = false
}
}
extension ViewController: StatsTextController {
func setItem(_ item: String?) {
title = item
}
}
Run your app and you will the most basic search experience: a UISearchBar with the number of results each time you write a query.
To get a more meaningful search experience, please follow our Getting Started Guide.
If you only require business logic modules in your project and use InstantSearchCore framework, add import InstantSearchCore to your source files.
Insights
InstantSearch Insights iOS library allows developers to capture search-related events. The events maybe related to search queries (such as click an conversion events used for Click Analytics or A/B testing). It does so by correlating events with queryIDs generated by the search API when a query parameter clickAnalytics=true is set. As well library allows to capture search-independent events which can be used for the purpose of search experience personalization. There are three types of these events which are currently supported: click, conversion and view.
Quick Start
Initialize the Insights client
You first need to initialize the Insights client. For that you need your Application ID and API Key. You can find them on your Algolia account. Also, for the purpose of personalization an application User Token can be specified via the corresponding optional parameter. In case of non-specified user token an automatically-generated application-wide user token will be used.
Insights.register(appId: "testApp", apiKey: "testKey", userToken: "testToken")
Sending metrics
Once that you registered your Application ID and the API Key you can easily start sending metrics.
Insights.shared?.clickedAfterSearch(eventName: "click event",
indexName: "index name",
objectID: "object id",
position: 1,
queryID: "query id")
Insights.shared?.convertedAfterSearch(eventName: "conversion event",
indexName: "index name",
objectIDs: ["obj1", "obj2"],
queryID: "query id")
Insights.shared?.viewed(eventName: "view event",
indexName: "index name",
filters: ["brand:apple"])
Logging and debuging
In case you want to check if the metric was sent correctly, you need to enable the logging first
Insights.shared(appId: "appId")?.isLoggingEnabled = true
After you enabled it, you can check the output for success or error messages
Events flush delay
By default the client transmits tracked events every 30 seconds. You can customize this delay by changing flushDelay value (in seconds) as follows:
Insights.flushDelay = 60
Setting API region
By default each analytics API call is geo-routed so that each call targets the closest API. Today the analytics API suports two regions: United States and Germany. You can specify the region your prefer to use as follows:
Insights.region = .de
Getting Help
- Need help? Ask a question to the Algolia Community or on Stack Overflow.
- Encountering an issue? Before reaching out to support, we recommend heading to our FAQ where you will find answers for the most common issues and gotchas with the framework.
- Found a bug? You can open a GitHub issue.
- Questions about Algolia? You can search our FAQ in our website.
Getting involved
- If you want to contribute please feel free to submit pull requests.
- If you have a feature request please open an issue.
- If you use InstantSearch in your app, we would love to hear about it! Drop us a line on discourse or twitter.
License
InstantSearch iOS is Apache 2.0 licensed.
17 Jan 1, 2023
22 Dec 25, 2022
2.5k Dec 21, 2022
1.2k Dec 17, 2022
3 Nov 16, 2022
89 Feb 25, 2022
12k Jan 2, 2023
34 Sep 26, 2022
117 Sep 2, 2022
682 Dec 29, 2022
5 Jul 12, 2022
5.3k Jan 2, 2023
175 Nov 19, 2022
3.3k Dec 21, 2022
5.9k Jan 1, 2023
851 Dec 17, 2022
360 Feb 4, 2022
12 Dec 26, 2022
225 Feb 11, 2022