Walkthrough: Add a Tangram map to an iOS application

With the Tangram iOS framework, you can easily get started and create 2D and 3D maps in your iOS application. The customizable stylesheet enables you to have the finest control over the rendering of your map, tweaking how the lighting, geometry, labels would look. The Tangram iOS framework is an open source project, and welcomes feedback. If you have any issue using the iOS framework, you can directly open an issue on GitHub and we will do our best to help you from there.

This walkthrough will be using Swift for code samples, but The Tangram iOS Framework can be used from both Objective-C and Swift.

You can follow this guide to add a Tangram map to your iOS application. If you are looking to use Tangram with other cartographic tools like search, geocoding or routing, you should check the Mapzen iOS SDK.

This guide assumes some knowledge of iOS software development. If you want more information about writing iOS applications, visit the Apple resources for iOS.

We recommend you to use Cocoapods in order to use the Tangram iOS framework. If you don't have it installed yet, learn how to at https://cocoapods.org/.

Run the simple map demo application

In order to run a simple demo app, and once CocoaPods has been installed, you can run the demo application by running the following:

pod try Tangram-es

This will open up XCode, you can then build and run the sample project.

sample project

Adding Tangram to an iOS application

1. Add the tangram binary Framework to your XCode project.

Using the recommended way of using the framework with CocoaPods, adding the Tangram Pod to your app is as simple as adding the following to your Podfile:

pod 'Tangram-es', '~> 0.6.1'

Then run from your shell:

pod install

You can learn more about setting up a Pod file from the CocoaPods documentation.

If you are not using CocoaPods, you can download the latest version of the framework from our releases, then simply drag and drop the framework into your iOS project. Then, from your poject settings under Embedded Binaries, click on + to add TangramMap.framework, and make sure that the framework appears in the build phases with Code Sign On Copy checked.

Xcode screenshot

If you are using CocoaPods, make sure to open your xcworkspace project (not xcodeproj).

2. Create a basic ViewController that inherits from TGMapViewController.

import UIKit
import TangramMap

class ViewController: TGMapViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
    }
}

TGMapViewController description can be found on the iOS framework documentation.

3. Add a GLKit View to your storyboard.

Make sure to select the storyboard you want the map to be rendered on, then add the GLKit View that Tangram will use to perform rendering.

GLKit view

Once added to your storyboard, make sure that the custom class of your GLKit View is referencing the custom class that we just created.

Create custom class

4. Add scene file to your application assets.

The scene file is a YAML document that specifies the appearance of your map. You can write your own scene file or use one of the Mapzen styles like Bubble Wrap, Walkabout, Cinnabar, or Refill. Once you've chosen a Mapzen scene or made your own, drag and drop the scene and all of its resources to your XCode project, and make sure that all the resources appear in the Copy Bundle Resources step of your iOS application Build Phases: XCode resources

Mapzen’s vector tile service provides GeoJSON, TopoJSON, and MVT tiles that you can use with Tangram. Mapzen scene files use this service as their data source. If you want to use Mapzen vector tiles, you will need to sign up for a free API key at mapzen.com/developers.

5. Initialize and load your scene at runtime.

With ViewController declared to load in your storyboard, you are now ready to load the scene:

class ViewController: TGMapViewController {

    override func viewWillAppear(_ animated: Bool) {
        let sceneURL = "walkabout-style-more-labels.yaml"
        super.loadSceneFileAsync(sceneURL, sceneUpdates: [ TGSceneUpdate(path: "global.sdk_mapzen_api_key", value: <YOUR_API_KEY_HERE>) ])
    }

    [...]
}

Next steps

In this guide, you learned how to add a Tangram map to your iOS application. Now you can: