MapLibreParticleLab/platform/ios/docs/pod-README.md

Mapbox iOS SDK

The Mapbox iOS SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa Touch applications on iOS 7.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the Mapbox GL Style Specification, applies them to vector tiles that conform to the Mapbox Vector Tile Specification, and renders them using OpenGL.

For more information, check out the Mapbox iOS SDK homepage and the full changelog online.

Installation

The Mapbox iOS SDK may be installed as either a dynamic framework or a static framework. (To reduce the download size, the static framework is omitted from some distributions; you may need to download the full package from the release page.)

{{DYNAMIC}}

Dynamic framework

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

1. Open the project editor and select your application target. Drag Mapbox.framework from the dynamic folder into the “Embedded Binaries” section of the General tab. (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.

2. 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.)

{{/DYNAMIC}} {{STATIC}}

Static framework

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

1. Drag the Mapbox.bundle and Mapbox.framework files in static into the Project navigator, checking "Copy items if needed". It should happen automatically, but ensure that:

   • Mapbox.framework is listed in your Link Binary With Libraries build phase.
   • Your 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.
   • Mapbox.bundle is in your target's Copy Bundle Resources build phase.

2. Optional As noted in the documentation you may use the provided Settings.bundle to provide a Telemetry opt out for users. To use the provided file, drag the Settings.bundle file from the release root folder into the Project navigator, checking "Copy items if needed". It should happen automatically, but ensure that:

   • Settings.bundle is in your target's Copy Bundle Resources build phase.

3. 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

{{/STATIC}}

Configuration

1. Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target. In the Info tab, set MGLMapboxAccessToken to your access token. You can obtain one from the Mapbox account page.

2. In order to show the user’s position on the map, you must first ask for their permission. In iOS 8 and above, this is accomplished by creating and setting the NSLocationAlwaysUsageDescription and/or NSLocationWhenInUseUsageDescription key in the Info.plist file.

3. (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 the provided Settings.bundle.

Usage

In a XIB or storyboard, add a Custom View and set its custom class to MGLMapView. If you need to manipulate the map view programmatically, import the Mapbox module in your view controller’s implementation file:

// ViewController.m
@import Mapbox;

// ViewController.swift
import Mapbox

Then switch to the Assistant Editor and create an outlet to the map view. (Control-drag from the map view in Interface Builder to a valid location in your view controller implementation.)

Full API documentation is included in this package, within the documentation folder. For more details, read “First steps with the Mapbox iOS SDK” and consult the online examples.

If you have any questions, please contact our support team. We welcome your bug reports and feature requests.