The perfect starting point to integrate Algolia within your Swift project
Documentation • Community Forum • Stack Overflow • Report a bug • FAQ • Support
✨
Features
- Pure cross-platform Swift client
- Typed requests and responses
- Widespread use of
Resulttype - Uses the power of
Codableprotocol for easy integration of your domain models - Thread-safe clients
- Detailed logging
- Injectable HTTP client
Install
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.
If you're a framework author and use Swift API Client as a dependency, update your Package.swift file:
let package = Package(
// 8.11.0 ..< 9.0.0
dependencies: [
.package(url: "https://github.com/algolia/algoliasearch-client-swift", from: "8.11.0")
],
// ...
)
Add import AlgoliaSearchClient to your source files.
Cocoapods
CocoaPods is a dependency manager for Cocoa projects.
To install Algolia Swift Client, simply add the following line to your Podfile:
pod 'AlgoliaSearchClient', '~> 8.11'
# pod 'InstantSearchClient', '~> 6.0' // Swift 4.2
# pod 'InstantSearchClient', '~> 5.0' // Swift 4.1
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/algoliasearch-client-swift" ~> 8.11
# github "algolia/algoliasearch-client-swift" ~> 6.0.0 // Swift 4.2
# github "algolia/algoliasearch-client-swift" ~> 5.0.0 // Swift 4.1
- Launch the following commands from the project directory (for v.8.0+)
carthage update
./Carthage/Checkouts/algoliasearch-client-swift/carthage-prebuild
carthage build
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.
💡
Getting Started
Initialize the client
To start, you need to initialize the client. To do this, you need your Application ID and API Key. You can find both on your Algolia account.
let client = Client(appID: "YourApplicationID", apiKey: "YourAdminAPIKey")
let index = client.index(withName: "your_index_name")
Push data
Without any prior configuration, you can start indexing contacts in the contacts index using the following code:
struct Contact: Encodable {
let firstname: String
let lastname: String
let followers: Int
let company: String
}
let contacts: [Contact] = [
.init(firstname: "Jimmie", lastname: "Barninger", followers: 93, company: "California Paint"),
.init(firstname: "Warren", lastname: "Speach", followers: 42, company: "Norwalk Crmc")
]
let index = client.index(withName: "contacts")
index.saveObjects(contacts, autoGeneratingObjectID: true) { result in
if case .success(let response) = result {
print("Response: \(response)")
}
}
Search
You can now search for contacts by firstname, lastname, company, etc. (even with typos):
index.search(query: "jimmie") { result in
switch result {
case .failure(let error):
print("Error: \(error)")
case .success(let response):
print("Response: \(response)")
do {
let foundContacts: [Contact] = try response.extractsHits()
print("Found contacts: \(foundContacts)")
} catch let error {
print("Contact parsing error: \(error)")
}
}
}
Configure
Settings can be customized to tune the search behavior. For example, you can add a custom sort by number of followers to the already great built-in relevance:
let settings = Settings()
.set(\.customRanking, to: [.desc("followers")])
index.setSettings(settings) { result in
if case .failure(let error) = result {
print("Error when applying settings: \(error)")
}
}
You can also configure the list of attributes you want to index by order of importance (first = most important):
Note: Since the engine is designed to suggest results as you type, you'll generally search by prefix. In this case the order of attributes is very important to decide which hit is the best:
let settings = Settings()
.set(\.searchableAttributes, to: ["lastname", "firstname", "company"])
index.setSettings(settings) { result in
if case .failure(let error) = result {
print("Error when applying settings: \(error)")
}
}
For full documentation, visit the Algolia Swift API Client's documentation.
📝
Examples
You can find code samples in the Algolia's API Clients playground.
Use the Dockerfile
If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our dedicated guide to learn more.
📄
License
Algolia Swift API Client is an open-sourced software licensed under the MIT license.
Notes
Objective-C support
The Swift API client is compatible with Objective-C up to version 7.0.5. Please use this version of the client if you're working with an Objective-C project.
Swift 3
You can use this library with Swift by one of the following ways:
pod 'AlgoliaSearch-Client-Swift', '~> 4.8.1'pod 'AlgoliaSearch-Client-Swift', :git => 'https://github.com/algolia/algoliasearch-client-swift.git', :branch => 'swift-3'
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 client.
- Found a bug? You can open a GitHub issue.
5 Oct 29, 2022
0 Jan 21, 2022
10 Dec 24, 2022
81 Oct 15, 2022
24 Dec 12, 2022
0 Aug 27, 2022
146 Nov 24, 2022
1 Jan 3, 2022
2 Jun 20, 2022
6 Nov 26, 2022
10 Dec 24, 2022
344 Jan 4, 2023
16 Jul 29, 2022
37 Nov 30, 2022
59 Jan 8, 2023
19 Dec 20, 2022
112 Dec 19, 2022
9 Aug 23, 2022
1 Jun 30, 2020