CircleCI Swift version iOS version Xcode version codecov swift-doc

Mapbox Search SDK for iOS

Table of contents

Overview

The Mapbox Search SDK is a developer toolkit to add location search on mobile devices. With the same speed and scale of the Mapbox Search API, the SDK is built specifically for on-demand and local search use cases, like ride-share, food delivery, and store finders apps. Whether your users are trying to find a place among the vast amount of data on a global map, or to find the exact location of a venue a few miles down the road, the Search SDK provides location search for countries all over the globe, in many different languages.

Previously, implementing search into your application required custom tuning with every API request to set a language, location biasing, and result types. There was no pre-built UI and no option for a user to see their search history, or save favorites.

The Mapbox Search SDK allows you to drop pre-tuned search into your application, removing the complexity of API configuration, while still giving you control to customize. It ships with an optional UI framework, or you can build a completely custom implementation with your own UI elements by using the core library. The Search SDK is pre-configured for autocomplete, local search biasing, and includes new features like category search, search history, and search favorites.

Requirements

  • iOS 11.0 and newer
  • Xcode 11.3 and newer
  • Swift 4.2 and newer
  • Objective-C is not supported
  • macOS/tvOS/watchOS platforms currently are not supported

Main features

  • Easy-to-use pre-tuned search options to integrate search into your app quickly.
    • Local search for a specific address or POI
  • Pre-configured and customizable category search for popular categories like cafes, ATMs, hotels, and gas stations.
  • On-device user search history
  • On-device favorites
  • Import/export customer data with your own protocols
  • Provide you own persistent providers for customer data like History or Favorites

Prerequisites

The SDK requires Carthage which you can install using Homebrew.

  1. Check that Homebrew is installed by running brew -v. If you don’t have Homebrew, install before proceeding.
  2. Update Homebrew data to install latest tools versions
    brew update
  3. Install Carthage (required version: 0.35 and newer) brew install carthage or brew upgrade carthage
  4. Setup .netrc file for sdk registry access
    1. Create .netrc file in user home directory ($HOME/.netrc, e.g. /Users/victorprivalov/.netrc)
    2. File content: machine api.mapbox.com login mapbox password sk.ey_your_access_token_wit_Read_permission
  5. Build dependencies: make dependencies

  6. Mapbox APIs require a Mapbox account and access token. Get an access token from the Mapbox account page. To run a Demo you can provide a token in different ways:

    1. Create a new file named mapbox or .mapbox in your home directory with content of your access token. We also support .mapbox file in the repository root folder. MapboxSearchDemoApplication will automatically handle this key and insert it in corresponding place.

      Note: Run pbpaste > ~/.mapbox in Terminal.app to insert you Pastebord (Command+C buffer) into .mapbox in Home directory.

    2. Open the Workspace, choose MapboxSearchDemoApplication project and select “Info” tab for “MapboxSearchDemoApplication” target. Here you can set your accessToken for MGLMapboxAccessToken key in “Custom iOS Target Properties” section.

    3. Provide your accessToken directly in argument named accessToken in SearchDrawer.make(:) method

Getting Started

Once you’ve installed the prerequisites, no additional steps are needed: Open the Workspace and use any available scheme. The SDK includes a demo app that you can run on your iOS device or simulator by choosing MapboxSearchDemoApplication.

Documentation

The link to iOS documentation will be added soon (instruction on how to build, usage the API, ready-to-use examples).

Project structure overview

MapboxSearch project consist of five targets:

  1. search-native.a (hidden; Bindgen generated Xcode project)
  2. MapboxCoreSearch.framework (hidden; Bindgen generated Xcode project)
  3. MapboxSearch.framework
  4. MapboxSearchUI.framework
  5. MapboxSearchDemoApplication

search-native.a written in C++ and MapboxCoreSearch.framework is generated by bindgen using Objective-C++ language. Both targets live in submodule and get compiled by scripts in this submodule.

While search-native.a implements most of the shared logic, MapboxSearch.framework contains all the platform business logic for Search.

MapboxSearchUI.framework provides a default UI implementation with customization points to meet the most common customer needs. The UI elements include a search bar with result list, category search icons, history and favorites management, and a combined search/category search UI. (Screenshots coming soon)

MapboxSearchDemoApplication provides a Demo app wih MapboxSearchUI.framework presentation over the basic MapView. To get access to nightly builds in TestFlight, make a request to Search iOS developers.

Distribution

Search SDK can be distributed by source code and binaries. Currently mapbox-search-ios repository is private and distribution by source code is for internal usage only (SPM, Carthage). SDK Registry with cocoapods used for the binaries distribution. Also there is search-ios public repo for binaries distribution via SPM and carthage.

Automated Distribution Guide

  1. (optional) Create release branch with semver compatible name (release/v1.5.0-alpha.14)
  2. Create semver compatible tag git tag v1.2.3-alpha.4
  3. Push tag to the origin git push --tags
  4. CircleCI job should be triggered, process can be tracked in Circle CI
  5. The job has multiple steps, creates PRs into docs and sdk-registry repos and has one blocking step, which requires manual approval (request-post-SDK_Registry-release).
    1. release-ios will post a PR into ios-sdk repository with documentation. You should approve and merge it. (example)
    2. release-ios will also post a PR into sdk-registry (aka api-downloads) It also should be approved and merged.(example)
    3. Now the job will stop and wait for approval of request-post-SDK_Registry-release. We should wait for sdk-registry to make our binaries available. Usually it takes about 20 mins. You can check that new version became available in carthage json
    4. Approve request-post-SDK_Registry-release.
  6. Sanity check:
    1. New version available in cocoapods
    2. New version available SPM (binaries from public repo)
    3. New version available in carthage (binaries from public repo)

Manual Distribution Guide

SDK Registry (Binaries)

  1. Build frameworks:

    1. To build both MapboxSearch and MapboxSearchUI frameworks run make products. The default output folder is Products in the repository root.

  2. Upload binary to SDK-Registry:

    1. Make sure you have Mapbox AWS account, if not then should create ticket in user-isolation repository request AWS account
    2. You need to install mbxcli to be able to upload artifacts to AWS S3.
    3. Run command mbx login default. After successful login AWS console will open in your default browser.
    4. In section AWS services' find subsectionAll servicesand then inside of itStorage. You should select theS3` item from it.
    5. From the list of buckets we should select mapbox-api-downloads-production.
    6. All search SDK versions published in v2/search-sdk/releases/. For each new version you should create a separate folder named as version number. Example of correct structure and naming you can see in 0.7.0 folder.For more details on SDK registry you can see SDK Registry FAQ and SDK Registry documentation

  3. Prepare sdk-registry config:

    1. Configs are located in api-downloads/config/search-sdk repository. Config specification can be found here.
    2. Create new config file or update existing. Each version requires a separate config file and should be named appropriate (e.g. 0.7.0.yaml).
    3. Config file content should contain a list of ios packages, look at 0.7.0.yaml for the example.
    4. Open PR with updated config file.

Cocoapods (Binaries)

  1. Update podspecs files:
    1. Podspec files located in mapbox-search-ios repository (MapboxSearch.podspec and MapboxSearchUI.podspec).
    2. In podspec files update the version field (s.version = 'new.version.number') and url to binaries if changed (s.source = { :http => "" }).
    3. In MapboxSearchUI.podspec file update dependency version (s.dependency 'MapboxSearch', "~> new.version.number").
    4. Validate updated podspecs by running mapbox-search-ios/scripts/pod_lint.sh (it will lint both podspec files).
    5. Open PR with updated podspecs.
    6. Upload podspecs to repository (internal or public). Instructions for how to upload pospec are in readme.md of podspecs repositories.

SPM (Sources)

Currently mapbox-search-ios repository is private and SPM only available for internal distribution.

  1. Make semver tag git tag v0.12.3
  2. Push tag to the origin git push --tags
  3. Create a new Github Release based on the created tag.
  4. Github releases used only to notify subscribers about new releases. Do Not attach any artefacts to the release.

Carthage (Sources, Deprecated)

Currently mapbox-search-ios repository is private and Carthage only available for internal distribution. But we do support carthage distribution with XCFrameworks (Required Carthage 0.38.0) Artifacts should be uploaded to SDK Registry (see section SDK Registry (Binaries) above)

Integration

Cocoapods

MapboxSearch

To integrate latest preview version of MapboxSearch into your Xcode project using CocoaPods, specify it in your Podfile: 

pod 'MapboxSearch', ">= 1.0.0-beta", "< 2.0"
MapboxSearchUI

To integrate latest preview version of MapboxSearchUI into your Xcode project using CocoaPods, specify it in your Podfile: 

pod 'MapboxSearchUI', ">= 1.0.0-beta", "< 2.0"

Carthage

Carthage integration by Source code is available for everybody with repository read access. Binaries available for public access.

Sources (internal)

Add following line in your project Cartfile:

github "mapbox/mapbox-search-ios" ~> 1.0.0-beta.7

Pay an attention that Carthage integration build MapboxSearch and MapboxSearchUI from sources and simultaneously.

Binaries (public)

Add following line in your project Cartfile:

github "mapbox/search-ios" ~> 1.0.0-beta.7

Binaries (public)

Carthage integration is available with XCFrameworks binaries(Required Carthage 0.38.0) Add following line in your project Cartfile:

binary "https://api.mapbox.com/downloads/v2/carthage/search-sdk/MapboxSearch.json" ~> 1.0.0-beta

Use this command to build dependencies.

carthage bootstrap --use-netrc --use-xcframeworks

Please keep in mind that Authorization done by netrc, check Prerequisites section above.

Swift Package Manager

Sources (internal)

dependencies: [
    .package(url: "https://github.com/mapbox/mapbox-search-ios.git")
]

Binaries (public)

dependencies: [
    .package(url: "https://github.com/mapbox/search-ios.git")
]

Contributing

We welcome feedback and code contributions!

If you found a bug or want to request a feature open a github issue. Please use the appropriate issue template.

Code of Conduct

Our Standards

Examples of behavior that contributes to creating a positive environment include:

  • Using welcoming and inclusive language.
  • Being respectful of differing viewpoints and experiences.
  • Gracefully accepting constructive criticism.
  • Focusing on what is best for the community.
  • Showing empathy towards other community members.

We recommend reading this blog post from Github on writing great PRs..

Versioning

We use SemVer for versioning. For the versions available, see the tags on repository.