MapsGL iOS - Getting Started

Getting started with MapsGL is quick and easy and requires that you have an active Xweather Flex subscription .

Supported Mapping Libraries

MapsGL SDK for Apple Platforms currently supports integration with the following third-party mapping libraries:

Library + Version	Controller	Adapter Library
Mapbox Maps , v11.x.x	`MapboxMapController`	`MapsGLMapbox`
MapLibre Native for iOS , v6.18.0+	`MapLibreMapController`	`MapsGLMapLibre`

Installing

Follow the series of steps outlined below for your desired method to get started using the Xweather MapsGL SDK for Apple Platforms:

Swift Package Manager

Create an Xweather account

Sign up for an Xweather Weather API and Maps subscription and setup your access keys as described in our Xweather Weather API’s getting started guide. We offer a free developer account for you to give our weather API a test drive.

Add the MapsGL SPM Package

In your iOS app Xcode project or workspace:

Run File menu ❯ Add Package Dependencies…. Or alternatively, navigate to your project settings’ Package Dependencies section.
In the top-right “Search or Enter Package URL” field, type https://github.com/vaisala-xweather/mapsgl-apple-sdk.
Note: The public mapsgl-apple-sdk repo publishes provider-specific Swift Package channels through branches. Use master for the latest Mapbox channel and maplibre for the latest MapLibre channel. If you want to pin to a specific release line instead of tracking the latest provider branch, use release/x.y.z for Mapbox or release/maplibre/x.y.z for MapLibre.
Click Add Package in the bottom-right.
Choose the branch that matches the provider channel you want to consume:
- master: latest Mapbox package channel
- maplibre: latest MapLibre package channel
- release/x.y.z: pinned Mapbox release line
- release/maplibre/x.y.z: pinned MapLibre release line
In the “Choose Package Products for mapsgl-apple-sdk” dialog, ensure your app target is selected under “Add to Target”, and click Add Package.

The SPM package manifest at the repo root is provider-specific per branch. The Mapbox branches resolve the Mapbox SDK and expose the Mapbox adapter product, while the MapLibre branches resolve MapLibre Native and expose the MapLibre adapter product.

A MapsGL static library will be added to your app target’s “Frameworks, Libraries, and Embedded Content” section, and Xcode will resolve the frameworks required by the MapsGL products you include.

Set up a map view

Set up an interactive map instance using your chosen provider. If you’re using Mapbox, follow the Mapbox Maps SDK for iOS installation instructions . If you’re using MapLibre, set up a MLNMapView using the MapLibre Native SDK.

Set up MapsGL with your map

Set up your Xweather account access keys for the SDK, create the MapsGL map controller for your provider, and add a weather layer to the map. Use import MapsGLMaps plus import MapsGLMapbox for Mapbox or import MapsGLMapLibre for MapLibre.

See below for sample code to get started quickly using MapsGL with Mapbox.

CocoaPods

Create an Xweather account

Add the MapsGL pod

First, ensure CocoaPods is installed (see CocoaPods’s Install instructions ).

In the same directory as your .xcodeproj:

Create a new (or update your existing) Podfile file containing the line under your app target:
```
pod 'MapsGL', '>= https://github.com/vaisala-xweather/mapsgl-apple-sdk/releases/tag/v1.6.0'
```
For a boilerplate Podfile and more information on the Podfile format, see the CocoaPods Get Started instructions .
Run pod install on the command line (in the same directory).
Open the generated ….xcworkspace with Xcode.

In the xcworkspace that CocoaPods generates, the MapsGL dependencies required by your chosen provider are integrated into the build system and will be compiled into the app when built.

Note: Ensure that you replace instances of import MapsGLMapbox with import MapsGL in your project’s source code files, as the name of the library CocoaPods builds is different than what SPM uses.

Set up a map view

Set up MapsGL with your map

Set up your Xweather account access keys for the SDK, create the MapsGL map controller for your provider, and add a weather layer to the map. Use import MapsGLMaps and import MapsGL with MapboxMapController for Mapbox-based setups. If you are using MapLibre, use MapLibreMapController with the MapLibre adapter module available in the Apple SDK package.

See below for sample code to get started quickly using MapsGL with Mapbox.

Carthage

Create an Xweather account

Add your map provider

Add your chosen map provider to your project/workspace and app target. If you’re using Mapbox, install Mapbox v11.0.0 or newer according to the Mapbox Maps SDK for iOS Installation instructions. If you’re using MapLibre, install the MapLibre Native SDK for iOS in your app target.

Create a Cartfile and run update

First, ensure Carthage is installed (see Carthage’s Quick Start instructions ).

In the same directory as your .xcodeproj or .xcworkspace:

Create a new (or update your existing) Cartfile file containing the line:
```
github "vaisala-xweather/mapsgl-apple-sdk" ~> 1.6.0
```
Run carthage update --use-xcframeworks on the command line (in the same directory).
In the Project Navigator on the left, select your project at the top, then select your app target under “TARGETS”.
Under the “General” tab, in the “Frameworks, Libraries, and Embedded Content” section, click the ＋ button and in the “Choose frameworks and libraries to add:” dialog click Add Other… ❯ Add Files… in the bottom-right.
Browse to the Carthage/Build sub-directory, ⌘-click each xcframework to select them all, then click Open to add them to your project.

Each xcframework should now appear both in the “Frameworks, Libraries, and Embedded Content” section, and in the Project Navigator under a “Frameworks” group.

Add the MapsGL provider adapter source code

Visit the MapsGL-Apple-SDK release page and download “MapsGL.zip”, then extract it.
Run File menu ❯ Add Files to “your-project-name”….
Browse to where you downloaded and extracted MapsGL.zip, select the matching provider adapter directory (MapsGLMapbox or MapsGLMapLibre), and click Add.
In the “Choose options for adding these files” dialog, ensure your app target is selected under “Targets:”, and click Finish.

Note: Ensure that you remove instances of import MapsGLMapbox or import MapsGLMapLibre from your project’s source code files when that adapter source is added directly to your project, as the import isn’t needed in that embedding mode.

Set up a map view

Set up MapsGL with your map

Set up your Xweather account access keys for the SDK, create the MapsGL map controller for your provider, and add a weather layer to the map. Use import MapsGLMaps to import the primary MapsGL library.

See below for sample code to get started quickly using MapsGL with Mapbox.

Manual Framework Embedding

Create an Xweather account

Add your map provider

Download the MapsGL xcframeworks

Visit the MapsGL-Apple-SDK release page and download “MapsGL.zip”.

Extract “MapsGL.zip”, resulting in:

MapsGLCore.xcframework
MapsGLRenderer.xcframework
MapsGLMaps.xcframework
MapsGLMapbox source code directory
MapsGLMapLibre source code directory

Add the MapsGL xcframeworks

In your iOS app Xcode project or workspace:

In the Project Navigator on the left, select your project at the top, then select your app target under “TARGETS”.
Under the “General” tab, in the “Frameworks, Libraries, and Embedded Content” section, click the ＋ button and in the “Choose frameworks and libraries to add:” dialog click Add Other… ❯ Add Files… in the bottom-right.
Browse to where you downloaded and extracted MapsGL.zip, ⌘-click each xcframework to select them all, then click Open to add them to your project.
For each of the “MapsGL….xcframework”s libraries, change the Embed setting to “Embed & Sign”.

Each xcframework should now appear both in the “Frameworks, Libraries, and Embedded Content” section, and in the Project Navigator under a “Frameworks” group.

Add the MapsGL provider adapter source code

Run File menu ❯ Add Files to “your-project-name”….
Browse to where you downloaded and extracted MapsGL.zip, select the provider adapter directory that matches your map library (MapsGLMapbox or MapsGLMapLibre), and click Add.
In the “Choose options for adding these files” dialog, ensure your app target is selected under “Targets:”, and click Finish.

Set up a map view

Set up MapsGL with your map

See below for sample code to get started quickly using MapsGL with Mapbox.

The following Swift sample code shows a Mapbox-based setup. If you are using MapLibre instead, use the corresponding MapLibre map view along with MapLibreMapController from MapsGLMapLibre.

SwiftUI


import SwiftUI
import MapboxMaps
import MapsGLMaps
import MapsGLMapbox // Needed only if you are using SPM
//import MapsGL // Needed only if you are using CocoaPods
import Combine
 
let xweatherClientID = "FILL_IN_WITH_YOUR_CLIENT_ID"
let xweatherClientSecret = "FILL_IN_WITH_YOUR_CLIENT_SECRET"
let mapboxAccessToken = "FILL_IN_WITH_YOUR_MAPBOX_PUBLIC_ACCESS_TOKEN"
 
struct MyMapView : View {
	class Coordinator {
		/// MapsGL's controller that manages adding/removing MapsGL weather layers to/from the `MapboxMaps.MapView`.
		var mapController: MapboxMapController!
		
		/// Holds Combine subscriptions to MapsGL events and other Combine subscriptions.
		var cancellables: Set<AnyCancellable> = []
	}
	private let coordinator = Coordinator()
	
	var body: some View {
		MapReader { proxy in
			Map(initialViewport: .camera(
					center: CLLocationCoordinate2D(latitude: 50.0, longitude: 10.0),
					zoom: 2.5
			))
			.mapStyle(.dark)
			.ignoresSafeArea()
			.onAppear {
				guard let map = proxy.map else { return }
				
				try! map.setProjection(.init(name: .mercator)) // Set 2D map projection
				
				// Set up the MapsGL `MapboxMapController`, which will handle
				// 	adding/removing MapsGL weather layers to the `MapboxMaps.MapView`.
				let mapController = MapboxMapController(
					map: map,
					window: UIWindow?.none,
					account: XweatherAccount(id: xweatherClientID, secret: xweatherClientSecret)
				)
				coordinator.mapController = mapController
				
				// Once the map has completed initial load…
				mapController.subscribe(to: MapEvents.Load.self) { _ in
					// Add the wind particles layer.
					do {
						var layerConfig = WeatherService.WindParticles(service: mapController.service)
						layerConfig.layer.paint.particle.density = .extreme
						try mapController.addWeatherLayer(config: layerConfig)
					} catch {
						NSLog("Failed to add weather layer: \(error)")
					}
				}.store(in: &coordinator.cancellables)
			}
		}
	}
	
	private static let _staticInit: Void = {
		MapboxOptions.accessToken = mapboxAccessToken
	}()
	private let _staticInit: Void = Self._staticInit
}
 
#Preview {
	MyMapView()
}

A full example of how to set up MapsGL with Mapbox with SwiftUI can be found in the mapsgl-apple-sdk repository’s Demo directory , particularly in this content view .

UIKit


import UIKit
import MapboxMaps
import MapsGLMaps
import MapsGLMapbox // Needed only if you are using SPM
//import MapsGL // Needed only if you are using CocoaPods
import Combine
 
let xweatherClientID = "FILL_IN_WITH_YOUR_CLIENT_ID"
let xweatherClientSecret = "FILL_IN_WITH_YOUR_CLIENT_SECRET"
let mapboxAccessToken = "FILL_IN_WITH_YOUR_MAPBOX_PUBLIC_ACCESS_TOKEN"
 
class MyMapViewController : UIViewController {
	@IBOutlet private var mapView: MapboxMaps.MapView!
	
	/// MapsGL's controller that manages adding/removing MapsGL weather layers to/from the `MapboxMaps.MapView`.
	private var controller: MapboxMapController!
	
	/// Holds Combine subscriptions to MapsGL events and other Combine subscriptions.
	private var cancellables: Set<AnyCancellable> = []
	
	override func viewDidLoad() {
		super.viewDidLoad()
		
		// Create a `MapboxMaps.MapView`
		mapView = MapboxMaps.MapView(frame: view.bounds)
		mapView.mapboxMap.styleURI = .dark
		try! mapView.mapboxMap.setProjection(.init(name: .mercator)) // Set 2D map projection
		mapView.mapboxMap.setCamera(to: .init(center: CLLocationCoordinate2D(latitude: 50.0, longitude: 10.0), zoom: 2.5))
		mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
		view.addSubview(mapView)
		
		// Set up the MapsGL `MapboxMapController`, which will handle adding and removing MapsGL layers to the `MapboxMaps.MapView`.
		let xweatherAccount = XweatherAccount(id: xweatherClientID, secret: xweatherClientSecret)
		controller = MapboxMapController(map: mapView, account: xweatherAccount)
		
		// Once the map has completed initial load…
		controller.onLoad.observe { _ in
			// Add the wind particles layer.
			do {
				var layerConfig = WeatherService.WindParticles(service: controller.service)
				layerConfig.layer.paint.particle.density = .extreme
				try controller.addWeatherLayer(config: layerConfig)
			} catch {
				NSLog("Failed to add weather layer: \(error)")
			}
		}.store(in: &cancellables)
	}
	
	private static let _staticInit: Void = {
		MapboxOptions.accessToken = mapboxAccessToken
	}()
	private let _staticInit: Void = MyMapViewController._staticInit
}

A full example of how to set up MapsGL with Mapbox with UIKit can be found in the mapsgl-apple-sdk repository’s Demo directory , particularly in this view controller .