The Mapzen iOS SDK
The Mapzen iOS SDK is a thin wrapper that packages up everything you need to use Mapzen services in your iOS applications.
We welcome feedback from the community on its usage. Feature requests are also welcome; label it appropriately as an "Enhancement". Feel free to also reach out to us using any of the other channels we have available on https://mapzen.com/.
Everything you need to get going using the Mapzen SDK
Interacting with the map
- Position, rotation, zoom, and tilt
- Markers, polylines, and polygons
- Switching styles
- Gesture delegates
- Current location
Search and routing
Major features include:
- High performance and highly customizable map rendering using OpenGL ES provided by Tangram-es.
- Driving directions and customizable route lines provided by Mapzen Turn-by-Turn.
- Geocoding and Point-of-Interest search provided by Mapzen Search.
- Several base map styles to suit most use cases.
And many more features than we can list here in a timely fashion.
How Do I Get The SDK?
Step 1: Get yourself a free Mapzen API Key.
Step 2: Install the SDK through Cocoapods.
Step 4: Let us know your thoughts! You can either open a new issue on GitHub or send us email at firstname.lastname@example.org.
Non-cocoapods usage at this point is not recommended, but can be accomplished. First, make sure to
git submodule update --init --recursive to get all the style sheets after cloning this repository. Second. you will need to include the 3 other dependencies we require: Tangram-es, OnTheRoad for iOS, and the Pelias iOS SDK. Note that your project will need to support Swift 3.
There's a couple of things you should probably know about up front:
- We only will be supporting Swift 3.x moving forward. Older versions of the SDK were written in Swift 2, but it is not recommended to use that as the project has changed dramatically since then, and we're continuing to add features all the time.
- If you wish to install the sample app to a device (recommended due to performance issues in the simulator), you will need to update the bundle identifier and the code signing in the Xcode project and go through the general code signing process necessary for installing to a device. This will require a free Apple Developer account.
- If you decide to use Cocoapods and pull directly from master, you will need to add
:submodules => trueto your podfile line. Otherwise submodules will not load in. The full line would look like
pod "Mapzen-ios-sdk", :git => 'https://github.com/mapzen/ios.git', :branch => 'master', :submodules => true
Configure Sample App API Key
There are two (optionally 3) ways to set your API key in the Sample App:
- Update SampleApp/Info.plist
$(MAPZEN_API_KEY) with your key:
-- OR --
- Create a new scheme and add an environment variable
ios-sdk scheme and then add your environment variable here:
-- OR --
- Manually change the code in the Sample App's AppDelegate.swift on line 31 to use your API key. Note that this will generate warnings about unused code.
Help us keep the lights on
v1.1.1 - Nov 22, 2017
v1.1.1 is a bugfix release to address GPU background usage causing crashes in iOS apps in the background (thanks for the bug reports!). Fixing this required we be able to support background location updates, so as a side effect the SDK now supports background location services! We'll be working on adding more documentation around that soon. For now, you can take a look at the DemoMapViewController in the sample app and see how it gets enabled. You will need to go through all the usual steps for enabling background location as well, so we recommend you still read through Apple's documentation on the topic!!
- Background location support is available!
- We now properly respect apps going into and out of background mode and properly limit GPU calls. https://github.com/mapzen/ios/issues/378
v1.1.0 - Oct 19, 2017
Welcome to the first major feature addition we have for our SDK! We're so grateful to all the feedback we've received from the community and look forward to working with you all as we drive towards our next set of goals!
We do want to point out there was 1 very minor change we had to make with this release due to underlying dependency changes where a property went from required to optional. It should affect almost no one given its location but lease see the release notes for more info!
- Theme support is now available for our SDK-provided style sheets! Check out some of our recent blog posts on the topic here and here.
- As part of the Themes work, we've laid foundational work for supporting custom style sheets. Please take a look at it and provide us with feedback by opening an issue! This work is considered experimental and we expect to change the protocol, perhaps significantly in the near future after we gather additional feedback, so we recommend not basing any production work on it just yet.
- We can now deploy correctly to the iOS app store (It's the little things).
- The map now renders at 60 frames per second for buttery smooth mapping.
- Memory management has been improved in upstream dependencies so we no longer have to remove and recreate the map and its associated attributes. Main code for this has been removed and we'll be removing supporting objects in a future release.
- Underlying marker implementations have been completely refactored for better performance.
Deprecations and API Changes
- We had to alter how we manage our underlying Tangram-es markers such that now they're optional in the marker protocols - https://github.com/mapzen/ios/blob/master/MapzenSDK/Marker.swift#L16 - this would only impact you if you were implementing your own custom markers against the marker protocols. Feel free to open an issue and we can assist.
- We've deprecated a couple methods and replaced them with more modern versions. You should start receiving warnings about it from the compiler if you're using any of them. Take a look in the source - the modern methods are right next to the deprecated methods. We're working on improving documentation for this in future releases.
- NOTE: We haven't deprecated the existing methods for loading stylesheets using the
MapStyleenum because of the experimental nature of the
StyleSheetprotocol, but that is the direction we're heading so it is very likely we will deprecate those methods in a future 1.x release and target removal for them in 2.0.
- Tangram-es upgraded to 0.8.1
- Pelias updated to 1.0.2
v1.0.1 - Oct 19, 2017
Fixed a font issue with stylesheets.
v1.0.0 - May 2, 2017
We're proud to announce the 1.0.0 version of our Mapzen iOS SDK! No code changes have been made since 0.4.1 (aka 1.0.0-RC2), so if you were using 0.4.1, upgrading to 1.0.0 should be smooth sailing.
As always, let us know about any issues by opening a Github issue!
v0.4.1 - May 1, 2017
We're prepping for releasing 1.0.0 to the world, and wanted to push out another release candidate for everyone to test out on Cocoapods.
Adding to all of the changes in the 0.4.0 build, this one includes a minor update to Tangram-es which has fixes for marker visibility bugs as well as improvements to fallback system font loading. See all of the details here