Quick Start with the Swift API Client

Supported platforms

The API client is compatible with Swift 5.0+ and supported on iOS, macOS, tvOS and watchOS.

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 Algolia as a dependency, update your Package.swift file:

1
2
3
4
5
6
7
let package = Package(
    // 8.0.0 ..< 9.0.0
    dependencies: [
        .package(url: "https://github.com/algolia/algoliasearch-client-swift", from: "8.0.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:

1
2
3
pod 'AlgoliaSearchClient', '~> 8.0'
# 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:
  Ruby

  Copy

  1
  2
  3
  github "algolia/algoliasearch-client-swift" ~> 8.0.0
  # 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 (only for version 8.0+)
  shell

  Copy

  1
  2
  3
   carthage update
   ./Carthage/Checkouts/algoliasearch-client-swift/carthage-prebuild
   carthage build
  

Quick Start

In 30 seconds, this quick start tutorial will show you how to index and search objects.

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.

1
2
3
4
import AlgoliaSearchClient

let client = SearchClient(appID: "YourApplicationID", apiKey: "YourAdminAPIKey")
let index = client.index(withName: "your_index_name")

The API key displayed here is your Admin API key. To maintain security, never use your Admin API key on your front end, nor share it with anyone. In your front end, use the search-only API key or any other key that has search-only rights.

If you are building a native app on mobile, make sure not to include the search API key directly in the source code. You should instead consider fetching the key from your servers during the app’s startup.

Push data

Without any prior configuration, you can start indexing contacts in the contacts index using the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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)")
  }
}

Configure

You can customize settings to fine tune the search behavior. For example, you can add a custom ranking by number of followers to further enhance the built-in relevance:

1
2
3
4
5
6
7
8
9
10
let settings = Settings()
  .set(\.customRanking, to: [.desc("followers")])
index.setSettings(settings) { result in
  switch result {
  case .failure(let error):
    print("Error when applying settings: \(error)")
  case .success:
    print("Success")
  }
}

You can also configure the list of attributes you want to index by order of importance (most important first).

Algolia is designed to suggest results as you type, which means you’ll generally search by prefix. In this case, the order of attributes is crucial to decide which hit is the best.

1
2
3
4
5
6
7
8
9
10
let settings = Settings()
  .set(\.searchableAttributes, to: ["lastname", "firstname", "company", "email", "city", "address"])
index.setSettings(settings) { result in
  switch result {
  case .failure(let error):
    print("Error when applying settings: \(error)")
  case .success:
    print("Success")
  }
}

Search

You can now search for contacts by firstname, lastname, company, etc. (even with typos):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Search for a first name
index.search(query: "jimmie") { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}
// Search for a first name with typo
index.search(query: "jimie") { result in
    if case .success(let response) = result {
      print("Response: \(response)")
    }
}
// Search for a company
index.search(query: "california paint") { result in
    if case .success(let response) = result {
      print("Response: \(response)")
    }
}
// Search for a first name and a company
index.search(query: "jimmie paint") { result in
    if case .success(let response) = result {
      print("Response: \(response)")
    }
}