MapLibreParticleLab/platform/ios/INSTALL.md

Integrating the Mapbox iOS SDK into your application

This document explains how to build a development version of Mapbox iOS SDK for use in your own Cocoa Touch application. To use a production-ready version of the SDK, see the Mapbox iOS SDK homepage.

Requirements

The Mapbox iOS SDK application builds against the iOS 7.0 SDK. It is intended to run on iOS 7.0 and above on the following devices and their simulators:

• iPhone 4S and above (5, 5c, 5s, 6, 6 Plus)
• iPad 2 and above (3, 4, Mini, Air, Mini 2, Air 2)
• iPod touch 5th generation and above

Building the SDK

1. Install core dependencies.

2. Install jazzy for generating API documentation:

   [sudo] gem install jazzy
   

3. Run make ipackage. The packaging script will produce a build/ios/pkg/ folder containing:

• a dynamic folder containing a dynamically-linked fat framework with debug symbols for devices and the iOS Simulator
• a static folder containing a statically-linked framework with debug symbols for devices and the iOS Simulator
• a documentation folder with HTML API documentation
• an example Settings.bundle containing an optional Mapbox Telemetry opt-out setting

Installation

There are a few ways to install the Mapbox iOS SDK:

CocoaPods

Currently, until #1437 is completed, to install a development version of Mapbox GL using CocoaPods you will need to build it from source manually per above.

1. Zip up the build product.

   cd build/ios/pkg/
   ZIP=mapbox-ios-sdk.zip
   rm -f ../${ZIP}
   zip -r ../${ZIP} *
   

2. Customize Mapbox-iOS-SDK.podspec to download this zip file.

   {...}
   
   m.source = {
       :http => "http://{...}/mapbox-ios-sdk.zip",
       :flatten => true
   }
   
   {...}
   

3. Update your app's Podfile to point to the Mapbox-iOS-SDK.podspec.

   pod 'Mapbox-iOS-SDK', :podspec => 'http://{...}/Mapbox-iOS-SDK.podspec'
   

4. Run pod update to grab the newly-built library.

Testing pre-releases with CocoaPods

To test pre-releases and/or betas, you can reference the pre-release like so in your Podfile:

pod 'Mapbox-iOS-SDK', podspec: 'https://raw.githubusercontent.com/mapbox/mapbox-gl-native/<insert branch or tag>/ios/Mapbox-iOS-SDK.podspec'

Dynamic framework

This is the recommended workflow for manually integrating the SDK into an application targeting iOS 8 and above:

1. Build from source manually per above.

2. Open the project editor, select your application target, then go to the General tab. Drag Mapbox.framework from the build/ios/pkg/dynamic/ directory into the “Embedded Binaries” section. (Don’t drag it into the “Linked Frameworks and Libraries” section; Xcode will add it there automatically.) In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.

3. In the Build Phases tab, click the + button at the top and select “New Run Script Phase”. Enter the following code into the script text field:

bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Mapbox.framework/strip-frameworks.sh"

(The last step, courtesy of Realm, is required for working around an iOS App Store bug when archiving universal binaries.)

Static framework

If your application targets iOS 7.x, you’ll need to install the static framework instead:

1. Build from source manually per above.

2. Drag the Mapbox.bundle and Mapbox.framework from the build/ios/pkg/static/ directory into the Project navigator. In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish. Open the project editor and select your application target to verify that the following changes occurred automatically:

   • In the General tab, Mapbox.framework is listed in the “Linked Frameworks and Libraries” section.
   • In the Build Settings tab, the “Framework Search Paths” (FRAMEWORK_SEARCH_PATHS) build setting includes the directory that contains Mapbox.framework. For most projects, the default value of $(inherited) $(PROJECT_DIR) should be sufficient.
   • In the Build Phases tab, Mapbox.bundle is listed in the “Copy Bundle Resources” build phase.

3. Back in the General tab, add the following Cocoa Touch frameworks and libraries to the “Linked Frameworks and Libraries” section:

   • GLKit.framework
   • ImageIO.framework
   • MobileCoreServices.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • libc++.tbd
   • libsqlite3.tbd
   • libz.tbd

Configuration

1. Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom iOS Target Properties” section, set MGLMapboxAccessToken to your access token. You can obtain an access token from the Mapbox account page.

2. (Optional) Mapbox Telemetry is a powerful location analytics platform included in this SDK. By default, anonymized location and usage data is sent to Mapbox whenever the host application causes it to be gathered. This SDK provides users with a way to individually opt out of Mapbox Telemetry. You can also add this opt-out setting to your application’s Settings screen using a Settings bundle. An example Settings.bundle is available in the build/ios/pkg/ directory; drag it into the Project navigator, checking “Copy items if needed” when prompted. In the project editor, verify that the following change occurred automatically:

   • In the General tab, Settings.bundle is listed in the “Copy Bundle Resources” build phase.

Usage

In a storyboard or XIB, add a view to your view controller. (Drag View from the Object library to the View Controller scene on the Interface Builder canvas.) In the Identity inspector, set the view’s custom class to MGLMapView. If you need to manipulate the map view programmatically:

1. Switch to the Assistant Editor.
2. Import the Mapbox module.
3. Connect the map view to a new outlet in your view controller class. (Control-drag from the map view in Interface Builder to a valid location in your view controller implementation.) The resulting outlet declaration should look something like this:

// ViewController.m
@import Mapbox;

@interface ViewController : UIViewController

@property (strong) IBOutlet MGLMapView *mapView;

@end

// ViewController.swift
import Mapbox

class ViewController: UIViewController {
    @IBOutlet var mapView: MGLMapView!
}